coulomb/kontextual-engine
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Release readiness polish

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-14 03:29:05 +02:00
parent d74913b184
commit 199ffe2a56
8 changed files with 376 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
CHANGELOG.md Normal file
View File

@@ -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.

4
README.md
View File

@@ -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`

66
docs/first-release-readiness.md
View File

@@ -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
```

115
docs/release-runbook-0.1.0.md Normal file
View File

@@ -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.

114
docs/release-security-configuration-storage-review.md Normal file
View File

@@ -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.

2
pyproject.toml
View File

@@ -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",
]

47
workplans/KONT-WP-0015-first-release-readiness.md
View File

@@ -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.

2
workplans/KONT-WP-0016-cmis-read-side-contract-maturity.md
View File

@@ -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