diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..4ea071d --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,53 @@ +# Changelog + +## 0.1.0 - Controlled Preview + +Date: 2026-05-14 + +### Added + +- Native knowledge-operations foundation: governed asset registry, metadata + schemas, relationships, retrieval, transformations, workflow jobs, service + API, audit records, and policy-gated operation contexts. +- Blob/content-stream foundation with in-memory, local filesystem, and optional + S3 adapters; representation content is deduplicated by digest and exposed + through native services and CMIS content-stream routes. +- Profiled CMIS 1.1 Browser Binding subset for controlled integrations: + repository/type discovery, navigation projections, object reads/writes, + content streams, change tokens, ACL discovery, relationships, change log, and + selected compatibility operations. +- Bounded CMIS read-side contract for simple document queries, common-property + ordering, relationship filters, ACL vocabulary, and explicit unsupported + diagnostics. +- Compact pytest performance-history monitor with rolling and daily summaries. +- State Hub registered workplans and timestamped CMIS assessment evidence. + +### Evidence + +- Full venv test suite: + `.venv/bin/python -m pytest -q` -> `166 passed`, `15 skipped`. +- OpenCMIS selected Browser Binding baseline: + `run-20260514T003705Z` -> completed, `0` unexpected findings, `0` waivers, + object/content passed, only local HTTP loopback warning remains. +- Packaging smoke: + `python3 -m build --sdist --wheel` succeeded for `0.1.0`. +- Clean install smoke: + installed `kontextual_engine-0.1.0-py3-none-any.whl[service]` in a throwaway + venv and verified `kontextual_engine.__version__`, `create_app`, and runtime + attachment. + +### Known Limitations + +- This is not a full CMIS certification and not a broad ECM replacement claim. +- CMIS support is Browser Binding only; AtomPub and Web Services are out of + scope. +- CMIS `getDescendants`, `getFolderTree`, PWC/checkin/checkout, full CMIS SQL, + policy mutation, retention/hold, renditions, and broad filing mutations are + intentionally unsupported. +- Multifiling is projection-only. +- `appendContentStream` is whole-object append through deduplicating storage; + chunk-level composition remains deferred. +- Preview deployments must put CMIS access points behind HTTPS termination. +- Optional `markdown` and `llm` extras point to local sibling repositories for + this controlled workspace preview; they are not required for the default or + service install. diff --git a/README.md b/README.md index b6201ab..d56051e 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,10 @@ Start here: - `docs/markitect-tool-capacity-risks.md` - `examples/markitect-tool-contract/` - `docs/test-performance-monitoring.md` +- `docs/first-release-readiness.md` +- `docs/release-runbook-0.1.0.md` +- `docs/release-security-configuration-storage-review.md` +- `CHANGELOG.md` - `docs/phase-memory-boundary.md` - `docs/system-layer-extraction-inventory.md` - `docs/system-layer-migration-backlog.md` diff --git a/docs/first-release-readiness.md b/docs/first-release-readiness.md index cff0b4b..5d4ac53 100644 --- a/docs/first-release-readiness.md +++ b/docs/first-release-readiness.md @@ -29,17 +29,17 @@ Out of scope for `0.1.0`: | Area | Gate | Current state | | --- | --- | --- | -| CMIS read-side contract | Query, navigation, relationship, ACL, and change-token contracts are release-stable or explicitly waived. | `KONT-WP-0016` implemented locally; full release verification still required. | -| Tests | Full suite passes in the project venv. | `.venv/bin/python -m pytest -q` passed: `166 passed`, `15 skipped` in `73.05s`; advisory performance drift warnings recorded. | +| CMIS read-side contract | Query, navigation, relationship, ACL, and change-token contracts are release-stable or explicitly waived. | Complete; see `docs/cmis-read-side-contract.md`. | +| Tests | Full suite passes in the project venv. | `.venv/bin/python -m pytest -q` passed: `166 passed`, `15 skipped` in `42.23s`; advisory performance drift warnings recorded. | | CMIS evidence | OpenCMIS selected baseline completes with no unexpected findings. | `run-20260514T003705Z` completed; object/content passed; only local HTTP warning remains. | | Transport | Released CMIS access points are served behind HTTPS. | Required deployment gate; local loopback warning is accepted only for harness runs. | -| Capability honesty | Scorecard, unsupported catalog, and examples match behavior. | Updated for `appendContentStream` and WP-0016 read-side contract; final doc review required. | -| Packaging | Version, dependencies, optional extras, and install smoke are checked. | `pyproject.toml` is already `0.1.0`; build/install smoke still required. | -| Configuration | Storage backend, S3 settings, local blob path, and environment defaults are documented. | Existing docs cover backends; release runbook should point to them. | -| Data safety | Blob cleanup, backups, restore path, and migration posture are documented. | Cleanup exists; backup/restore release notes still needed. | -| Security | Actor headers, access-point profiles, secrets, and dependency/license review are done. | Profile model exists; release security review still required. | -| Operations | Health checks, logs, performance history, and known warnings are documented. | Health and performance monitor exist; release runbook still needed. | -| State | State Hub consistency check passes after release docs/workplan updates. | Passed after WP-0015 registration. | +| Capability honesty | Scorecard, unsupported catalog, and examples match behavior. | Complete; scorecard updated for WP-0016 and `run-20260514T003705Z`. | +| Packaging | Version, dependencies, optional extras, and install smoke are checked. | Complete; sdist/wheel build and clean `[service]` install smoke passed. | +| Configuration | Storage backend, S3 settings, local blob path, and environment defaults are documented. | Complete; see `docs/release-security-configuration-storage-review.md`. | +| Data safety | Blob cleanup, backups, restore path, and migration posture are documented. | Complete for preview; backup/restore expectations documented in the release review and runbook. | +| Security | Actor headers, access-point profiles, secrets, and dependency/license review are done. | Complete for controlled preview; HTTPS/authenticated edge remains deployment requirement. | +| Operations | Health checks, logs, performance history, and known warnings are documented. | Complete; see `docs/release-runbook-0.1.0.md`. | +| State | State Hub consistency check passes after release docs/workplan updates. | Complete; State Hub consistency check passed with `0 fail`, `0 warn`, `0 info`. | ## Known Accepted Limitations @@ -51,24 +51,54 @@ Out of scope for `0.1.0`: production-facing access points. - Performance drift warnings from pytest are advisory unless repeated under a quiet system baseline; the current run flagged several CMIS API tests. +- Optional `markdown` and `llm` extras point at sibling repositories in this + workspace and are not part of the default/service install path. ## Release Procedure 1. Run `.venv/bin/python -m pytest -q`. 2. Run the OpenCMIS selected baseline through `guide-board` and persist the evidence document. -3. Run State Hub consistency check and ensure workplans are registered. -4. Run packaging smoke: build wheel/sdist and import `kontextual_engine` from a - clean install. -5. Review security/configuration: HTTPS termination, profile exposure, secrets, +3. Run packaging smoke: build wheel/sdist and import `kontextual_engine` from a + clean install with the `[service]` extra. +4. Review security/configuration: HTTPS termination, profile exposure, secrets, local/S3 blob backend settings, and dependency licenses. -6. Update `CHANGELOG.md` or release notes with capabilities, known limitations, +5. Update `CHANGELOG.md` or release notes with capabilities, known limitations, and accepted warnings. +6. Run State Hub consistency check and ensure workplans are registered. 7. Tag the release only after the gates above are green or explicitly waived. ## Release Decision -The current foundation is close to a controlled `0.1.0` preview. With the -`KONT-WP-0016` read-side contract settled locally, the remaining release work is -mainly discipline around repeatable verification, packaging, deployment -posture, and clearly documented limits. +The current foundation is ready for a controlled `0.1.0` preview. No release +tag has been created by this workplan; tag creation remains a deliberate +operator action after reviewing the release notes and deployment target. + +## Packaging Evidence + +```text +python3 -m build --sdist --wheel --outdir /tmp/kontextual-release-smoke-20260514T010625Z/dist +``` + +Built artifacts: + +- `kontextual_engine-0.1.0.tar.gz` +- `kontextual_engine-0.1.0-py3-none-any.whl` + +Clean install smoke: + +```text +/tmp/kontextual-release-smoke-20260514T010625Z/venv/bin/python \ + -m pip install /tmp/kontextual-release-smoke-20260514T010625Z/dist/kontextual_engine-0.1.0-py3-none-any.whl[service] + +/tmp/kontextual-release-smoke-20260514T010625Z/venv/bin/python \ + -c "import kontextual_engine; from kontextual_engine import ServiceRuntime, create_app; app=create_app(ServiceRuntime()); print(kontextual_engine.__version__); print(app.title); print(hasattr(app.state, 'kontextual_runtime'))" +``` + +Smoke output: + +```text +0.1.0 +Kontextual Engine Service API +True +``` diff --git a/docs/release-runbook-0.1.0.md b/docs/release-runbook-0.1.0.md new file mode 100644 index 0000000..74072a7 --- /dev/null +++ b/docs/release-runbook-0.1.0.md @@ -0,0 +1,115 @@ +# Release Runbook 0.1.0 + +Date: 2026-05-14 +Release posture: controlled preview + +## Purpose + +This runbook defines the repeatable checks and operator expectations for the +`kontextual-engine` `0.1.0` controlled preview. It is a release envelope, not a +new product scope. + +## Preflight + +Run from `/home/worsch/kontextual-engine`: + +```sh +.venv/bin/python -m pytest -q +python3 -m build --sdist --wheel --outdir /tmp/kontextual-release-smoke-20260514T010625Z/dist +``` + +Expected evidence for this pass: + +- full suite: `166 passed`, `15 skipped`, +- package build: `kontextual_engine-0.1.0.tar.gz` and + `kontextual_engine-0.1.0-py3-none-any.whl`, +- clean install smoke: wheel plus `[service]` extra imports + `kontextual_engine`, creates `create_app(ServiceRuntime())`, and attaches + `app.state.kontextual_runtime`. + +## CMIS Evidence + +Run the selected OpenCMIS Browser Binding baseline through `guide-board` and +`open-cmis-tck`. On this workstation, use port `8010` for the temporary engine +endpoint because port `8000` is already occupied by another local service. + +Current accepted evidence: + +- run: `run-20260514T003705Z`, +- assessment: `cmis-browser-baseline`, +- result: completed, +- policy: `0` unexpected findings and `0` waivers, +- object/content: pass, +- only warning: local HTTP loopback transport. + +The local HTTP warning is accepted only for harness runs. Preview deployments +must serve production-facing CMIS access points behind HTTPS termination. + +## Runtime Start + +The app is currently exposed as a FastAPI factory: + +```sh +PYTHONPATH=src .venv/bin/uvicorn 'kontextual_engine.api.app:create_app' \ + --factory \ + --host 127.0.0.1 \ + --port 8010 +``` + +For deployment, instantiate `ServiceRuntime` with explicit durable repository, +blob storage, and policy gateway adapters instead of relying on the default +in-memory runtime. + +## Health And Observability + +Required operator checks: + +- `/health` returns process health. +- `/ready` returns readiness for the configured runtime. +- `/version` returns the service version. +- `/openapi.json` is available when the service extra is installed. +- Pytest performance history is retained under + `.pytest_cache/kontextual/performance-history.json` during development runs. + +Performance drift warnings are advisory unless reproduced under a quiet system +baseline. Keep the compact history file for trend awareness; use dedicated +profiling experiments for detailed performance investigations. + +## Data Safety + +Preview deployments must define: + +- registry persistence location and backup schedule, +- blob backend and backup or bucket-versioning strategy, +- restore rehearsal for registry plus blob content, +- retention policy for raw assessment artifacts and logs, +- rollback point before migrations or adapter changes. + +For SQLite-backed previews, stop writes before copying the database or use a +SQLite backup method. For local blob storage, back up the whole content-addressed +root. For S3, enable bucket versioning or equivalent object protection and back +up IAM/policy configuration alongside data. + +## Rollback + +Rollback for `0.1.0` preview means: + +1. Stop the service or remove it from routing. +2. Preserve current logs, State Hub references, registry database, and blob + root/bucket state for analysis. +3. Restore the previous package artifact and previous registry/blob snapshot. +4. Re-run `/health`, `/ready`, smoke import, and a small read/write scenario. +5. Record the rollback reason in State Hub before resuming external traffic. + +## Tag Gate + +Do not create the release tag until: + +- full venv tests pass, +- OpenCMIS selected baseline is persisted, +- package build and clean install smoke pass, +- security/config/storage review is current, +- State Hub consistency is clean, +- release notes are updated. + +No tag is created by this runbook automatically. diff --git a/docs/release-security-configuration-storage-review.md b/docs/release-security-configuration-storage-review.md new file mode 100644 index 0000000..4896faf --- /dev/null +++ b/docs/release-security-configuration-storage-review.md @@ -0,0 +1,114 @@ +# Release Security, Configuration, And Storage Review + +Date: 2026-05-14 +Release: `0.1.0` controlled preview +Status: reviewed for release readiness + +## Security Boundary + +`kontextual-engine` uses explicit operation contexts, actor metadata, profile +gates, policy decisions, and audit records. The preview release is suitable for +controlled integrations, not anonymous internet exposure. + +Production-facing deployments must provide: + +- HTTPS termination for CMIS and native API access, +- authentication and trusted actor-header injection at the edge, +- request logging without leaking secrets or content bytes, +- restricted network exposure for admin/export profiles, +- backup and restore procedures for registry and blob storage. + +## CMIS Access-Point Profiles + +| Profile | Exposure | Release note | +| --- | --- | --- | +| `readonly-browser` | Public/internal read subset; no mutations. | Safe default profile for controlled read clients. | +| `governed-authoring` | Public/internal read plus governed object/content mutations. | Requires authenticated actors and policy review before external use. | +| `admin-export` | Broad sensitivity visibility, service-account actor type required. | Must not be exposed to general users; service-account routing only. | +| `compat-tck` | Browser Binding compatibility profile with selected mutation support. | Intended for OpenCMIS harness and compatibility testing, not normal production traffic. | + +CMIS optional capabilities are advertised conservatively. Unsupported services +return structured CMIS diagnostics rather than partial silent behavior. + +## Actor Headers + +The service runtime accepts actor context through headers such as: + +- `X-Actor-Id`, +- `X-Actor-Type`, +- `X-Actor-Display-Name`, +- `X-Actor-Groups`, +- `X-Delegated-Actor-*`, +- `X-Correlation-Id`, +- `X-Request-Scope`, +- `X-Policy-Scope`. + +These headers are trust-bearing. A production gateway must authenticate the +caller, strip inbound spoofed actor headers, and inject the trusted actor +context itself. Service-account routes such as `admin-export` must be restricted +to service-account identities. + +## Secrets + +No committed example, target profile, or runtime default embeds service secrets. +The OpenCMIS harness currently uses anonymous local loopback access for the +compatibility profile. S3 credentials must come from the deployment environment, +standard AWS provider chain, or secret manager, not from repository files. + +## Storage Configuration + +Supported storage posture: + +- `InMemoryAssetRegistryRepository` and `InMemoryBlobStorage`: tests and local + smoke only; no persistence. +- `SQLiteAssetRegistryRepository`: local-first durable preview registry. +- `LocalBlobStorage`: content-addressed local blob root with digest-derived + paths. +- `S3BlobStorage`: optional `kontextual-engine[s3]` backend using + digest-derived object keys behind the blob port. + +The domain model stores representation metadata and `storage_ref`; the blob +backend is an infrastructure choice. + +## Backup And Restore Expectations + +For a durable preview: + +- back up the registry database and blob storage together at a consistent point, +- record the package version, configuration, and active access-point profiles, +- for local blobs, back up the complete content-addressed root, +- for S3, enable bucket versioning or object-lock-equivalent safeguards where + available, +- restore registry and blob storage into a staging environment before declaring + backup coverage sufficient. + +Blob cleanup must use dry-run first. Active cleanup may delete only blobs proven +unreferenced by the registry. + +## Dependency And Packaging Review + +Default install dependencies: + +- `pydantic>=2.0`. + +Release extras: + +- `service`: FastAPI, HTTPX, Uvicorn. +- `storage`: SQLAlchemy. +- `s3`: Boto3. +- `dev`: Pytest. +- `markdown` and `llm`: local sibling-repository extras for this controlled + workspace preview. + +The local sibling extras are explicit optional extras and are not needed for +the default or service install. Before publishing outside this workspace, either +replace those file URLs with published package references or omit those extras +from the published distribution. + +## Release Decision + +Security/configuration/storage posture is acceptable for a controlled preview +when deployed behind authenticated HTTPS routing with explicit durable storage +configuration and documented backup/restore procedures. It is not acceptable to +expose the default in-memory runtime or the `compat-tck` profile as a general +production endpoint. diff --git a/pyproject.toml b/pyproject.toml index 3ecd589..a0da8b9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -8,7 +8,7 @@ version = "0.1.0" description = "Headless knowledge runtime for persistent, operable structured knowledge" readme = "README.md" requires-python = ">=3.12" -license = { text = "MIT" } +license = "MIT" dependencies = [ "pydantic>=2.0", ] diff --git a/workplans/KONT-WP-0015-first-release-readiness.md b/workplans/KONT-WP-0015-first-release-readiness.md index ef85889..7b6b2b6 100644 --- a/workplans/KONT-WP-0015-first-release-readiness.md +++ b/workplans/KONT-WP-0015-first-release-readiness.md @@ -4,7 +4,7 @@ type: workplan title: "First Release Readiness" domain: markitect repo: kontextual-engine -status: active +status: completed owner: codex topic_slug: markitect planning_priority: high @@ -28,7 +28,10 @@ reproducible, honest, operable, and easy to validate. - `docs/first-release-readiness.md` - `docs/cmis-1-1-capability-scorecard.md` -- `docs/cmis-opencmis-tck-release-readiness-evidence-2026-05-13T223537Z.md` +- `docs/cmis-opencmis-tck-release-readiness-evidence-2026-05-14T003705Z.md` +- `docs/release-runbook-0.1.0.md` +- `docs/release-security-configuration-storage-review.md` +- `CHANGELOG.md` - `docs/blob-storage-content-streaming-workplan.md` - `workplans/KONT-WP-0016-cmis-read-side-contract-maturity.md` - `pyproject.toml` @@ -48,7 +51,7 @@ waived for an internal-only release. ```task id: KONT-WP-0015-T001 -status: todo +status: done priority: high state_hub_task_id: "82ee46b4-d865-4741-b60c-083f06210c4d" ``` @@ -65,7 +68,7 @@ Acceptance: ```task id: KONT-WP-0015-T002 -status: todo +status: done priority: high state_hub_task_id: "7e5398e0-0c54-44cc-b63c-04bc9f0edabb" ``` @@ -83,7 +86,7 @@ Acceptance: ```task id: KONT-WP-0015-T003 -status: todo +status: done priority: high state_hub_task_id: "724b6882-f76e-4452-91d8-e56dda215cfe" ``` @@ -101,7 +104,7 @@ Acceptance: ```task id: KONT-WP-0015-T004 -status: todo +status: done priority: medium state_hub_task_id: "298b2628-139e-4e74-8790-dd0e92d091f3" ``` @@ -118,7 +121,7 @@ Acceptance: ```task id: KONT-WP-0015-T005 -status: todo +status: done priority: medium state_hub_task_id: "bf42c477-2d21-48dc-9469-a6ce90982928" ``` @@ -130,3 +133,33 @@ Acceptance: - Any waived gate has an explicit rationale and follow-up workplan item. - The release tag is created only after the go/no-go gates are complete or intentionally waived. + +## Implementation Evidence + +Completed on 2026-05-14 for the controlled `0.1.0` preview: + +- Full venv suite passed: + `.venv/bin/python -m pytest -q` -> `166 passed`, `15 skipped` in `42.23s`. +- Focused CMIS tests passed: + `.venv/bin/python -m pytest tests/cmis/test_cmis_browser_binding_api.py tests/cmis/test_cmis_runtime_browser_binding.py tests/cmis/test_cmis_compliance_flags.py tests/cmis/test_cmis_contract_examples.py -q` + -> `37 passed`. +- OpenCMIS selected baseline persisted: + `run-20260514T003705Z`, completed, `0` unexpected findings, object/content + passed, only local HTTP loopback warning remains. +- Packaging smoke passed: + `python3 -m build --sdist --wheel --outdir /tmp/kontextual-release-smoke-20260514T010625Z/dist` + produced wheel and sdist. +- Clean install smoke passed: + installed + `/tmp/kontextual-release-smoke-20260514T010625Z/dist/kontextual_engine-0.1.0-py3-none-any.whl[service]` + into a throwaway venv and verified package version, FastAPI app creation, and + runtime attachment. +- `pyproject.toml` license metadata was modernized to the SPDX-style string + `MIT`, removing the setuptools license-table deprecation warning from release + builds. +- Release runbook, security/configuration/storage review, and changelog were + added. + +No release tag was created by this workplan. The tag gate is documented in +`docs/release-runbook-0.1.0.md`; tagging remains a deliberate operator action +after final review of the target deployment. diff --git a/workplans/KONT-WP-0016-cmis-read-side-contract-maturity.md b/workplans/KONT-WP-0016-cmis-read-side-contract-maturity.md index 181456b..26d7a72 100644 --- a/workplans/KONT-WP-0016-cmis-read-side-contract-maturity.md +++ b/workplans/KONT-WP-0016-cmis-read-side-contract-maturity.md @@ -285,7 +285,7 @@ Full suite verification with service extras: ```text .venv/bin/python -m pytest -q -Result: 166 passed, 15 skipped in 73.05s +Result: 166 passed, 15 skipped in 42.23s ``` The run emitted advisory performance-drift warnings for several API tests. They