contracts: add shared content/build/release family

docs/contract-additions/shared-content-build-release-family-v0.md

@@ -0,0 +1,57 @@
+# Shared Content / Build / Release Family v0
+
+This additive contract family introduces shared object shapes that can be reused across:
+
+- SourceOS artifact definitions and release lanes
+- socios build / promotion automation
+- workstation execution evidence
+- office/editor export and publication lanes
+- platform bundle publication
+- catalog and promotion surfaces
+
+## Design intent
+
+The goal is not to force all domains into one execution engine.
+The goal is to let all domains share one object-language for:
+
+- desired content
+- frozen overlays and inputs
+- build requests
+- releases
+- enrollment/consumption profiles
+- evidence bundles
+- catalog entries
+- access profiles
+
+This keeps governance, provenance, and lifecycle semantics aligned even when the
+runtime/build substrate differs.
+
+## Object family
+
+- `ContentSpec`
+- `OverlayBundle`
+- `BuildRequest`
+- `ReleaseManifest`
+- `EnrollmentProfile`
+- `EvidenceBundle`
+- `CatalogEntry`
+- `AccessProfile`
+
+## Boundaries
+
+These schemas are additive. They do **not** replace:
+- `ReleaseReceipt`
+- `RunRecord`
+- `PolicyDecision`
+- `CapabilityToken`
+- existing fog / agent-plane / governance families
+
+Instead, they provide a cross-domain object layer that those families can reference.
+
+## Follow-on
+
+The next tranche after this family lands should add:
+- example payloads
+- fixture validation
+- explicit bindings from runner/evidence/catalog implementations
+- transport-boundary notes for local subprocess IPC vs remote TriTRPC transport

schemas/AccessProfile.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/AccessProfile.json",
+  "title": "AccessProfile",
+  "description": "A reusable access and consumption profile describing who may consume or act on governed content in which environments and for which purposes.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "specVersion", "name"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:access-profile:",
+      "description": "Stable URN identifier. Pattern: urn:srcos:access-profile:<local-id>"
+    },
+    "type": {
+      "const": "AccessProfile",
+      "description": "Discriminator constant — always \"AccessProfile\"."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version of this document, e.g. \"2.0.0\"."
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable access profile name."
+    },
+    "subjects": {
+      "type": "array",
+      "items": {"type": "string"},
+      "description": "Refs to subject classes, principals, groups, or identities covered by the profile."
+    },
+    "purposes": {
+      "type": "array",
+      "items": {"type": "string"},
+      "description": "Named purposes for which access is allowed."
+    },
+    "allowedContentRefs": {
+      "type": "array",
+      "items": {"type": "string"},
+      "description": "Optional allowlist of content or release refs this profile governs."
+    },
+    "allowedEnvironments": {
+      "type": "array",
+      "items": {"type": "string"},
+      "description": "Named environments or rings in which the profile is valid."
+    },
+    "obligations": {
+      "type": "array",
+      "items": {"type": "string"},
+      "description": "Named obligations or control requirements attached to this profile."
+    },
+    "expiresAt": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "Optional ISO 8601 expiry for the profile or current issuance."
+    }
+  }
+}

schemas/BuildRequest.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/BuildRequest.json",
+  "title": "BuildRequest",
+  "description": "A request to compose a ContentSpec plus zero or more OverlayBundles into one or more output artifacts or bundles.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "specVersion", "contentSpecRef", "outputs", "requestedAt"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:build-request:",
+      "description": "Stable URN identifier. Pattern: urn:srcos:build-request:<local-id>"
+    },
+    "type": {
+      "const": "BuildRequest",
+      "description": "Discriminator constant — always \"BuildRequest\"."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version of this document, e.g. \"2.0.0\"."
+    },
+    "contentSpecRef": {
+      "type": "string",
+      "description": "Reference to the ContentSpec being composed."
+    },
+    "overlayRefs": {
+      "type": "array",
+      "items": {"type": "string"},
+      "description": "Optional overlay bundle refs to apply during composition."
+    },
+    "outputs": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "enum": ["iso", "pxe", "raw", "qcow2", "ami", "bootc", "ostree", "bundle", "docs-export", "other"]
+      },
+      "description": "Requested output artifact surfaces."
+    },
+    "channel": {
+      "type": ["string", "null"],
+      "description": "Optional release channel target such as dev, qa, or prod."
+    },
+    "architecture": {
+      "type": ["string", "null"],
+      "description": "Optional architecture target such as x86_64 or arm64."
+    },
+    "enrollmentProfileRef": {
+      "type": ["string", "null"],
+      "description": "Optional enrollment profile ref for install/runtime consumption."
+    },
+    "parameters": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Execution-time parameters that do not change the canonical object family."
+    },
+    "requestedBy": {
+      "type": ["string", "null"],
+      "description": "Optional subject or actor ref that requested the build."
+    },
+    "requestedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 date-time when the build request was created."
+    }
+  }
+}

schemas/CatalogEntry.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/CatalogEntry.json",
+  "title": "CatalogEntry",
+  "description": "A searchable index record for a governed object, release, or artifact family without redefining the canonical object itself.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "specVersion", "objectRef", "objectType", "status", "updatedAt"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:catalog-entry:",
+      "description": "Stable URN identifier. Pattern: urn:srcos:catalog-entry:<local-id>"
+    },
+    "type": {
+      "const": "CatalogEntry",
+      "description": "Discriminator constant — always \"CatalogEntry\"."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version of this document, e.g. \"2.0.0\"."
+    },
+    "objectRef": {
+      "type": "string",
+      "description": "Reference to the canonical object represented by this catalog entry."
+    },
+    "objectType": {
+      "type": "string",
+      "description": "Type name of the canonical object, such as ReleaseManifest or EvidenceBundle."
+    },
+    "title": {
+      "type": ["string", "null"],
+      "description": "Optional title for indexing and presentation."
+    },
+    "labels": {
+      "type": "object",
+      "additionalProperties": {"type": "string"},
+      "description": "Index labels, tags, or dimensions used for discovery."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["draft", "frozen", "published", "superseded", "restricted", "archived"],
+      "description": "Catalog-visible lifecycle state."
+    },
+    "evidenceBundleRef": {
+      "type": ["string", "null"],
+      "description": "Optional EvidenceBundle ref associated with the indexed object."
+    },
+    "authorityRef": {
+      "type": ["string", "null"],
+      "description": "Optional ref to the authority or namespace governing this entry."
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 date-time when this catalog entry was last updated."
+    }
+  }
+}

schemas/ContentSpec.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/ContentSpec.json",
+  "title": "ContentSpec",
+  "description": "A canonical desired-content specification that describes a buildable or publishable unit before execution or release.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "specVersion", "name", "kind"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:content-spec:",
+      "description": "Stable URN identifier. Pattern: urn:srcos:content-spec:<local-id>"
+    },
+    "type": {
+      "const": "ContentSpec",
+      "description": "Discriminator constant — always \"ContentSpec\"."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version of this document, e.g. \"2.0.0\"."
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable name of the content specification."
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["os-flavor", "overlay-family", "document-export", "automation-bundle", "workspace-pack", "platform-bundle", "model-release", "other"],
+      "description": "Logical content category."
+    },
+    "sourceRefs": {
+      "type": "array",
+      "items": {"type": "string"},
+      "description": "Optional source refs such as git commits, OCI digests, or upstream artifact IDs."
+    },
+    "ownerRef": {
+      "type": ["string", "null"],
+      "description": "Optional owner or authority reference."
+    },
+    "labels": {
+      "type": "object",
+      "additionalProperties": {"type": "string"},
+      "description": "Human or machine labels for indexing and policy."
+    },
+    "policyTags": {
+      "type": "array",
+      "items": {"type": "string"},
+      "description": "Policy and governance tags relevant to this content."
+    },
+    "targetSurfaces": {
+      "type": "array",
+      "items": {"type": "string"},
+      "description": "Named surfaces where this content may be built, installed, published, or consumed."
+    }
+  }
+}

schemas/EnrollmentProfile.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/EnrollmentProfile.json",
+  "title": "EnrollmentProfile",
+  "description": "A profile that describes how an installed or activated system should register, enroll, and receive content after boot or first-run.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "specVersion", "name", "registrationMode"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:enrollment-profile:",
+      "description": "Stable URN identifier. Pattern: urn:srcos:enrollment-profile:<local-id>"
+    },
+    "type": {
+      "const": "EnrollmentProfile",
+      "description": "Discriminator constant — always \"EnrollmentProfile\"."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version of this document, e.g. \"2.0.0\"."
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable enrollment profile name."
+    },
+    "activationKeyRef": {
+      "type": ["string", "null"],
+      "description": "Optional activation or registration-key reference."
+    },
+    "hostGroupRef": {
+      "type": ["string", "null"],
+      "description": "Optional host-group or grouping reference."
+    },
+    "lifecycleEnvironmentRef": {
+      "type": ["string", "null"],
+      "description": "Optional lifecycle environment ref such as dev, qa, or prod."
+    },
+    "bootstrapUrl": {
+      "type": ["string", "null"],
+      "description": "Optional bootstrap or enrollment URL."
+    },
+    "trustAnchorRefs": {
+      "type": "array",
+      "items": {"type": "string"},
+      "description": "Trust anchors or certificate refs required for enrollment."
+    },
+    "registrationMode": {
+      "type": "string",
+      "enum": ["local_only", "online_registration", "bootstrap_token", "signed_intent"],
+      "description": "How the consumer enrolls or registers after boot/install."
+    },
+    "policyTags": {
+      "type": "array",
+      "items": {"type": "string"},
+      "description": "Governance or operational tags attached to the enrollment profile."
+    }
+  }
+}