feat: retain utilized MI knowledge references as provenance (#55) #101

Merged

kilo merged 1 commit from issue-55-mi-utilized-reference into develop

2026-10-26 18:01:27 +00:00

kilo commented

2026-10-26 16:49:55 +00:00

Member

Scope

Refs #55 (keep open). Bounded offline utilized-reference consumer: retain and validate the mi_utilization reference the Router emits in its public selection envelope, as provenance only. No direct MI reads, no sidecar/cut decoding, no freshness/TTL/authority semantics, no live producer access, no Router contract change, no harness adoption.

Producer contract (verified read-only)

Router #176 consumer merged at 4162f6fa9f774beaf6e92d86b7ebc92f306da4bd consuming MI publication d65891668b7e79f7b666c021f02a1b4bf8c4ca9c: /v1/select returns {"schema_version":1,"decision":…,"mi_utilization":…?} where the reference is exactly {source:"model_intelligence", identifier:"urn:mi:utilization:sha256:<64hex>", version:"mi.utilization-working/1"}.

Changes

core/knowledge.py: UtilizedKnowledge — corrupt grammar refuses the envelope (existing INVALID_RESPONSE path); a grammar-valid reference outside the producer contract is retained as explicit unsupported_version; export_document labels retention states not_retained/utilized/unsupported_version with authority=provenance-only, distribution=local-only.
Allocation.knowledge_utilization + allocation codec v3: immutable Attempt-bound retention at preparation; v1/v2 documents and bytes unchanged; v3 requires a validated retention document and permits null requirements evidence on the reference path; tampered/mislabeled retention refuses decode; restart decodes the original reference.
Adapter _decision extracts and validates mi_utilization; the reference never affects runtime compatibility, identity or authority (negative-tested).
Task/reference exports surface the labeled reference; the shared envelope fixture carries a valid reference so the two-work-unit composition and router-outage/different restart tests assert Attempt-bound retention and restart stability end to end.
NOTICE records the Apache-2.0 producer-contract adaptation; successor.md G06 row updated.

Not implemented (issue remains open)

Direct MI harness-interface evidence reads (AC4 conditional clause; the no-authority boundary is enforced and tested), any utilization sidecar or cut decoding, freshness/withdrawal semantics beyond the reference grammar (Router-side), live producer access.

Validation

make check: 1503 passed, 85 skipped, 106 subtests; format/lint/basedpyright/import-linter/secret-scan/diff gates pass.
make package-check: reproducible sdist/wheel and installed smoke checks pass.
New tests: 46 (grammar/states/codec/tamper/restart/export; adapter retention/absent/unsupported/corrupt/no-authority; composition retention + restart stability; legacy byte identity).

Base f4d86ea0a8e1b048d186fae01d49bb2283fc99d6; head fdc2aa98a7922d3c8610eac1dc3edfb17c601f8b.

## Scope Refs #55 (keep open). Bounded offline utilized-reference consumer: retain and validate the `mi_utilization` reference the Router emits in its public selection envelope, as provenance only. No direct MI reads, no sidecar/cut decoding, no freshness/TTL/authority semantics, no live producer access, no Router contract change, no harness adoption. ## Producer contract (verified read-only) Router #176 consumer merged at `4162f6fa9f774beaf6e92d86b7ebc92f306da4bd` consuming MI publication `d65891668b7e79f7b666c021f02a1b4bf8c4ca9c`: `/v1/select` returns `{"schema_version":1,"decision":…,"mi_utilization":…?}` where the reference is exactly `{source:"model_intelligence", identifier:"urn:mi:utilization:sha256:<64hex>", version:"mi.utilization-working/1"}`. ## Changes - `core/knowledge.py`: `UtilizedKnowledge` — corrupt grammar refuses the envelope (existing INVALID_RESPONSE path); a grammar-valid reference outside the producer contract is retained as explicit `unsupported_version`; `export_document` labels retention states `not_retained`/`utilized`/`unsupported_version` with `authority=provenance-only`, `distribution=local-only`. - `Allocation.knowledge_utilization` + allocation codec v3: immutable Attempt-bound retention at preparation; v1/v2 documents and bytes unchanged; v3 requires a validated retention document and permits null requirements evidence on the reference path; tampered/mislabeled retention refuses decode; restart decodes the original reference. - Adapter `_decision` extracts and validates `mi_utilization`; the reference never affects runtime compatibility, identity or authority (negative-tested). - Task/reference exports surface the labeled reference; the shared envelope fixture carries a valid reference so the two-work-unit composition and router-outage/different restart tests assert Attempt-bound retention and restart stability end to end. - NOTICE records the Apache-2.0 producer-contract adaptation; successor.md G06 row updated. ## Not implemented (issue remains open) Direct MI harness-interface evidence reads (AC4 conditional clause; the no-authority boundary is enforced and tested), any utilization sidecar or cut decoding, freshness/withdrawal semantics beyond the reference grammar (Router-side), live producer access. ## Validation - `make check`: 1503 passed, 85 skipped, 106 subtests; format/lint/basedpyright/import-linter/secret-scan/diff gates pass. - `make package-check`: reproducible sdist/wheel and installed smoke checks pass. - New tests: 46 (grammar/states/codec/tamper/restart/export; adapter retention/absent/unsupported/corrupt/no-authority; composition retention + restart stability; legacy byte identity). Base `f4d86ea0a8e1b048d186fae01d49bb2283fc99d6`; head `fdc2aa98a7922d3c8610eac1dc3edfb17c601f8b`.

kilo added 1 commit

2026-10-26 16:49:56 +00:00