diff --git a/Makefile b/Makefile index 11bf0e4..9551850 100644 --- a/Makefile +++ b/Makefile @@ -1,8 +1,14 @@ -.PHONY: validate validate-spine smoke carry +.PHONY: validate validate-spine smoke carry emit-service-manifest release-dry-run validate: validate-spine python3 tools/validate.py +emit-service-manifest: + cat service-manifest/functional-service.v1.json + +release-dry-run: validate smoke carry + @echo "release-dry-run OK: manifest + maturity spine validated, offline smoke passed, SourceOS carry emitted (disabled-by-default)." + validate-spine: python3 tools/validate_spine.py diff --git a/docs/LAB_SURFACE.md b/docs/LAB_SURFACE.md new file mode 100644 index 0000000..d5cf9e9 --- /dev/null +++ b/docs/LAB_SURFACE.md @@ -0,0 +1,35 @@ +# EmbeddingLab — lab surface + +`embeddinglab` is a **lab-only** workspace: it emits governed functional-service +manifests and evaluation evidence for downstream SocioProphet services. It does not +self-promote models into production and does not carry mutable model state into SourceOS. + +## Surfaces + +Enumerated in [`../lab.manifest.json`](../lab.manifest.json): + +- embeddings +- rerankers +- hybrid-retrieval-preparation +- vector-evaluation +- semantic-indexing + +## Service manifest + +The primary functional surface is declared in +[`../service-manifest/functional-service.v1.json`](../service-manifest/functional-service.v1.json), +which conforms to the canonical `functional-service.v1` schema +(`SocioProphet/functional-model-surfaces`). Inputs, outputs, evals, governance flags, and +the SourceOS carry policy are all declared there. + +## Evidence + +- Deterministic offline smoke: `make smoke` (the M2 promotion gate). +- Maturity record: [`../repo.maturity.yaml`](../repo.maturity.yaml) (`repo-maturity.v1`). +- Promotion dry-run gate: `make release-dry-run` (validate + smoke + carry). + +## Boundary + +Lab-only. No model weights, datasets, secrets, or credentials are committed. Scaffolding +directories (`datasets/`, `evals/`, `adapters/`, `training-runs/`) hold **references and +provenance only**. diff --git a/docs/PROPHET_INTEGRATION.md b/docs/PROPHET_INTEGRATION.md new file mode 100644 index 0000000..42e6ddd --- /dev/null +++ b/docs/PROPHET_INTEGRATION.md @@ -0,0 +1,22 @@ +# EmbeddingLab — Prophet integration + +How this lab hands off to the wider SocioProphet estate. All handoff targets are declared +in [`../lab.manifest.json`](../lab.manifest.json) under `governanceHandoff` and in the +service manifest `governance` / `sourceosCarry` blocks. + +| Target | Relationship | +|--------|--------------| +| `SocioProphet/holmes` | consumes the embedding/rerank surface as a product capability | +| `SocioProphet/model-router` | routes to the governed surface | +| `SocioProphet/model-governance-ledger` | receives promotion evidence (evals, provenance) | +| `SocioProphet/guardrail-fabric` | enforces guardrail policies on the surface | +| `SocioProphet/functional-model-surfaces` | canonical schema authority for the manifest | +| `SourceOS-Linux/sourceos-model-carry` | disabled-by-default SourceOS carry reference | + +## Governance handoff + +- `governance.ledgerRequired` / `guardrailRequired` / `routingRequired` are all `true` in + the service manifest — the surface cannot be promoted without ledger evidence, guardrail + policy, and a routing entry. +- `sourceosCarry.carriesMutableModelState` is `false` and `clientRefRequired` is `true`: + SourceOS carries only a signed client reference, never mutable model state.