feat(ocrlab): maturity spine — repo-maturity.v1 + lab.manifest + canonical functional-service

.github/workflows/validate.yml

@@ -1,17 +1,20 @@
 name: validate
-
 on:
   push:
   pull_request:
-
 jobs:
   validate:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Validate ocrlab
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install strict-validation deps
+        run: pip install pyyaml jsonschema
+      - name: make validate (spine + functional-service, offline)
         run: make validate
-      - name: Offline smoke test
+      - name: make smoke (deterministic offline)
         run: make smoke
-      - name: Emit SourceOS carry fixture
-        run: make carry
+      - name: Strict jsonschema validation of maturity record
+        run: python3 tools/validate_maturity.py schemas/repo-maturity.schema.json repo.maturity.yaml

Makefile

@@ -1,8 +1,11 @@
-.PHONY: validate smoke carry
+.PHONY: validate validate-spine smoke carry
 
-validate:
+validate: validate-spine
 	python3 tools/validate.py
 
+validate-spine:
+	python3 tools/validate_spine.py
+
 smoke:
 	python3 tools/smoke.py
 

adapters/README.md

@@ -0,0 +1,3 @@
+# adapters/
+
+Adapter **references** (LoRA/PEFT/prompt adapters) by URN or digest only. No adapter weights are committed. `service-manifest` `model.adapterRefs` cites entries here. Adapters never carry mutable state into SourceOS.

datasets/README.md

@@ -0,0 +1,3 @@
+# datasets/
+
+Dataset **references and provenance manifests only** — no raw datasets, no model weights, no secrets are committed here. Each entry records source, license, and a content digest so promotion evidence can cite verifiable dataset provenance.

evals/README.md

@@ -0,0 +1,3 @@
+# evals/
+
+Evaluation fixtures and signed eval results for governed promotion. The offline smoke (`make smoke`) is the M2 gate; richer eval references are cited from `service-manifest/functional-service.v1.json` under `evals.references`.

lab.manifest.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": "lab.manifest.v1",
+  "lab": "ocrlab",
+  "repository": "SociOS-Linux/ocrlab",
+  "modality": "ocr",
+  "boundary": "lab-only: emits governed functional-service manifests and evaluation evidence for downstream platform services; must not self-promote models into production and must not carry mutable model state into SourceOS image builds.",
+  "surfaces": [
+    "document-text-extraction",
+    "layout-analysis",
+    "table-extraction",
+    "handwriting-recognition",
+    "document-evidence-extraction"
+  ],
+  "serviceManifests": [
+    "service-manifest/functional-service.v1.json"
+  ],
+  "governanceHandoff": {
+    "ledger": "SocioProphet/model-governance-ledger",
+    "guardrail": "SocioProphet/guardrail-fabric",
+    "router": "SocioProphet/model-router",
+    "productSurface": "SocioProphet/holmes",
+    "sourceosCarry": "SourceOS-Linux/sourceos-model-carry"
+  },
+  "sourceosCarry": {
+    "allowed": true,
+    "carriesMutableModelState": false,
+    "clientRefRequired": true
+  }
+}

repo.maturity.yaml

@@ -0,0 +1,48 @@
+schemaVersion: repo-maturity.v1
+repository: SociOS-Linux/ocrlab
+plane: socios-lab
+status: experimental
+canonicality: reference
+owners:
+  - SociOS-Linux
+maturity:
+  level: M2
+  targetLevel: M3
+  evidence:
+    - README.md states lab purpose, lab-only boundary, and integration points.
+    - service-manifest/functional-service.v1.json conforms to functional-service.v1.
+    - lab.manifest.json enumerates 5 governed lab surfaces.
+    - make validate exits 0 (offline, deterministic).
+    - CI runs make validate + strict jsonschema validation on every push/PR.
+validation:
+  commands:
+    - make validate
+    - make smoke
+  ciRequired: true
+  lastKnownStatus: passing
+integrations:
+  - repository: SocioProphet/functional-model-surfaces
+    relationship: emits functional-service.v1 manifests
+    required: true
+  - repository: SocioProphet/model-governance-ledger
+    relationship: sends promotion evidence
+    required: true
+  - repository: SocioProphet/sociosphere
+    relationship: registers maturity/evidence status
+    required: true
+  - repository: SocioProphet/holmes
+    relationship: provides the ocr functional surface to Holmes
+    required: false
+  - repository: SocioProphet/model-router
+    relationship: routable governed surface
+    required: false
+  - repository: SocioProphet/guardrail-fabric
+    relationship: guardrail policy enforcement
+    required: false
+  - repository: SourceOS-Linux/sourceos-model-carry
+    relationship: disabled-by-default SourceOS carry reference
+    required: false
+nextActions:
+  - Add negative fixtures under fixtures/invalid/ (>=2 per schema) to reach M3.
+  - Wire promotion evidence into SocioProphet/model-governance-ledger.
+  - Register maturity record with SocioProphet/sociosphere workspace-inventory.

schemas/functional-service.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.socioprophet.org/functional-model-surfaces/functional-service.v1.json",
+  "title": "SocioProphet Functional Service Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "service",
+    "function",
+    "model",
+    "inputs",
+    "outputs",
+    "evals",
+    "governance",
+    "sourceosCarry"
+  ],
+  "properties": {
+    "schemaVersion": { "type": "string", "const": "functional-service.v1" },
+    "service": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "name", "ownerRepository", "status"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_.-]+$" },
+        "name": { "type": "string" },
+        "ownerRepository": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$" },
+        "status": { "type": "string", "enum": ["draft", "experimental", "candidate", "approved", "deprecated"] },
+        "description": { "type": "string" }
+      }
+    },
+    "function": {
+      "type": "string",
+      "enum": [
+        "speech",
+        "ocr",
+        "image",
+        "video",
+        "translation",
+        "embedding",
+        "reranking",
+        "timeseries",
+        "graph",
+        "nlp",
+        "language-intelligence",
+        "routing",
+        "guardrail",
+        "agent-tool"
+      ]
+    },
+    "model": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["modelRef", "mutableStatePolicy"],
+      "properties": {
+        "modelRef": { "type": "string" },
+        "adapterRefs": { "type": "array", "items": { "type": "string" } },
+        "runtime": { "type": "string" },
+        "mutableStatePolicy": { "type": "string", "enum": ["forbidden-in-sourceos", "lab-only", "governed-runtime-only"] }
+      }
+    },
+    "inputs": { "type": "array", "items": { "type": "string" } },
+    "outputs": { "type": "array", "items": { "type": "string" } },
+    "evals": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["required", "references"],
+      "properties": {
+        "required": { "type": "boolean" },
+        "references": { "type": "array", "items": { "type": "string" } },
+        "minimumPromotionGate": { "type": "string" }
+      }
+    },
+    "governance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ledgerRequired", "guardrailRequired", "routingRequired"],
+      "properties": {
+        "ledgerRequired": { "type": "boolean" },
+        "guardrailRequired": { "type": "boolean" },
+        "routingRequired": { "type": "boolean" },
+        "policyRefs": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "sourceosCarry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["allowed", "carriesMutableModelState", "clientRefRequired"],
+      "properties": {
+        "allowed": { "type": "boolean" },
+        "carriesMutableModelState": { "type": "boolean", "const": false },
+        "clientRefRequired": { "type": "boolean" },
+        "launchProfileRefs": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

schemas/repo-maturity.schema.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.socioprophet.org/functional-model-surfaces/repo-maturity.v1.json",
+  "title": "SocioProphet Repository Maturity Record",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "repository",
+    "plane",
+    "status",
+    "maturity",
+    "owners",
+    "canonicality",
+    "validation",
+    "integrations"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "repo-maturity.v1"
+    },
+    "repository": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$"
+    },
+    "plane": {
+      "type": "string",
+      "enum": [
+        "standards",
+        "runtime",
+        "governance",
+        "sourceos-carry",
+        "socios-lab",
+        "workspace-governance",
+        "cli",
+        "research",
+        "archive"
+      ]
+    },
+    "status": {
+      "type": "string",
+      "enum": ["active", "experimental", "incubating", "archival", "deprecated"]
+    },
+    "maturity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["level", "targetLevel", "evidence"],
+      "properties": {
+        "level": {
+          "type": "string",
+          "enum": ["M0", "M1", "M2", "M3", "M4", "M5"]
+        },
+        "targetLevel": {
+          "type": "string",
+          "enum": ["M1", "M2", "M3", "M4", "M5"]
+        },
+        "evidence": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "owners": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" }
+    },
+    "canonicality": {
+      "type": "string",
+      "enum": ["canonical", "reference", "experimental", "archive", "stub"]
+    },
+    "validation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["commands", "ciRequired"],
+      "properties": {
+        "commands": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "ciRequired": { "type": "boolean" },
+        "lastKnownStatus": {
+          "type": "string",
+          "enum": ["unknown", "passing", "failing", "not-configured"]
+        }
+      }
+    },
+    "integrations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["repository", "relationship"],
+        "properties": {
+          "repository": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$"
+          },
+          "relationship": { "type": "string" },
+          "required": { "type": "boolean" }
+        }
+      }
+    },
+    "nextActions": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

service-manifest/functional-service.v1.json

@@ -0,0 +1,54 @@
+{
+  "schemaVersion": "functional-service.v1",
+  "service": {
+    "id": "ocrlab.holmes.ocr-pilot",
+    "name": "OCRLab Holmes OCR Pilot",
+    "ownerRepository": "SociOS-Linux/ocrlab",
+    "status": "experimental",
+    "description": "Offline deterministic ocr functional surface emitted by ocrlab for governed promotion."
+  },
+  "function": "ocr",
+  "model": {
+    "modelRef": "urn:socioprophet:functional-model:ocrlab:deterministic-ocr:v0",
+    "adapterRefs": [],
+    "runtime": "python-stdlib-offline-smoke",
+    "mutableStatePolicy": "forbidden-in-sourceos"
+  },
+  "inputs": [
+    "image/document",
+    "text/corpus"
+  ],
+  "outputs": [
+    "ocr/features",
+    "ranking/candidates",
+    "evidence/smoke-receipt"
+  ],
+  "evals": {
+    "required": true,
+    "references": [
+      "examples/smoke-input.json",
+      "examples/smoke-output.json",
+      "evidence/smoke-receipt.example.json"
+    ],
+    "minimumPromotionGate": "candidate requires signed eval and dataset provenance"
+  },
+  "governance": {
+    "ledgerRequired": true,
+    "guardrailRequired": true,
+    "routingRequired": true,
+    "policyRefs": [
+      "SocioProphet/model-governance-ledger",
+      "SocioProphet/guardrail-fabric",
+      "SocioProphet/model-router",
+      "SocioProphet/holmes"
+    ]
+  },
+  "sourceosCarry": {
+    "allowed": true,
+    "carriesMutableModelState": false,
+    "clientRefRequired": true,
+    "launchProfileRefs": [
+      "urn:srcos:model-carry:functional-service:ocrlab-holmes-pilot"
+    ]
+  }
+}