@openship/protocol 0.0.1

package/README.md

@@ -0,0 +1,12 @@
+# @openship/protocol
+
+Canonical OpenShip 1.0 types, validators, source digest/diff helpers, selector matching, safe path/base64 utilities, browser discovery retrieval, and skill synchronization.
+
+```js
+import { fetchOpenShip, validateSystems } from "@openship/protocol";
+
+const imported = await fetchOpenShip("https://example.com");
+if (imported.snapshot.kind === "systems") validateSystems(imported.snapshot.document);
+```
+
+The package contains the exact canonical `skills/openship` schemas, examples, and references. See the repository root README for the generated-skill workflow.

package/bin/openship.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+import { cp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  validateChangesAccepted,
+  validateChangesDocument,
+  validateChangesPolicy,
+  validateChangesStatus,
+  validateChangesSubmission,
+  validateChangesViolation,
+  validateDiscovery,
+  validateSources,
+  validateSystems,
+} from "../src/index.js";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const meta = JSON.parse(await readFile(join(packageRoot, "dist", "package-meta.json"), "utf8"));
+const skillSource = join(packageRoot, "dist", "skill");
+
+async function digestDirectory(root, excludes = new Set()) {
+  const files = [];
+  async function walk(directory) {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const absolute = join(directory, entry.name);
+      if (entry.isDirectory()) await walk(absolute);
+      else {
+        const path = relative(root, absolute).split("\\").join("/");
+        if (!excludes.has(path)) files.push(path);
+      }
+    }
+  }
+  await walk(root);
+  files.sort();
+  const records = [];
+  for (const path of files) {
+    const hash = createHash("sha256").update(await readFile(join(root, path))).digest("hex");
+    records.push(`${path}\0${hash}\n`);
+  }
+  return { files, digest: `sha256:${createHash("sha256").update(records.join("")).digest("hex")}` };
+}
+
+const [command, rawDestination, ...rest] = process.argv.slice(2);
+if (command === "sync-skill") {
+  if (!rawDestination) throw new Error("Usage: openship sync-skill <destination>");
+  const destination = resolve(rawDestination);
+  await rm(destination, { recursive: true, force: true });
+  await mkdir(dirname(destination), { recursive: true });
+  await cp(skillSource, destination, { recursive: true });
+  const result = await digestDirectory(destination);
+  await writeFile(join(destination, "UPSTREAM.json"), `${JSON.stringify({
+    ...meta,
+    packageDigest: result.digest,
+    digestExcludes: ["UPSTREAM.json"],
+  }, null, 2)}\n`);
+  console.log(`OpenShip skill synchronized (${result.files.length} files, ${result.digest}).`);
+} else if (command === "verify-skill") {
+  if (!rawDestination) throw new Error("Usage: openship verify-skill <destination>");
+  const destination = resolve(rawDestination);
+  const provenance = JSON.parse(await readFile(join(destination, "UPSTREAM.json"), "utf8"));
+  const result = await digestDirectory(destination, new Set(provenance.digestExcludes ?? []));
+  const canonical = await digestDirectory(skillSource);
+  if (
+    provenance.package !== meta.package
+    || provenance.packageVersion !== meta.packageVersion
+    || provenance.sourceCommit !== meta.sourceCommit
+    || provenance.packageDigest !== canonical.digest
+    || result.digest !== canonical.digest
+    || JSON.stringify(result.files) !== JSON.stringify(canonical.files)
+  ) {
+    throw new Error(`OpenShip skill mismatch. Expected ${provenance.packageDigest}; got ${result.digest}.`);
+  }
+  console.log(`OpenShip skill verified (${result.files.length} files, ${result.digest}).`);
+} else if (command === "validate") {
+  const paths = [rawDestination, ...rest].filter(Boolean);
+  if (paths.length === 0) throw new Error("Usage: openship validate <document.json> [bundle.json]");
+  const values = await Promise.all(paths.map(async (path) => JSON.parse(await readFile(resolve(path), "utf8"))));
+  const value = values[0];
+  if (value.capability === "discovery") validateDiscovery(value);
+  else if (value.capability === "systems") validateSystems(value);
+  else if (value.capability === "sources") validateSources(value, values[1]);
+  else if (value.capability === "changes") {
+    if (value.files && value.title) validateChangesSubmission(value);
+    else if (value.writable) validateChangesPolicy(value);
+    else if (value.violations) validateChangesViolation(value);
+    else if (value.statusUrl) validateChangesAccepted(value);
+    else if (value.status) validateChangesStatus(value);
+    else validateChangesDocument(value);
+  }
+  else throw new Error(`Unsupported capability ${String(value.capability)}.`);
+  console.log("OpenShip document is valid.");
+} else {
+  throw new Error("Usage: openship <sync-skill|verify-skill|validate> ...");
+}

package/dist/package-meta.json

@@ -0,0 +1,7 @@
+{
+  "openship": "1.0",
+  "package": "@openship/protocol",
+  "packageVersion": "0.0.1",
+  "source": "https://github.com/openshipdev/openship/tree/main/skills/openship",
+  "sourceCommit": "40e94cc1a5c7eb06787d22257df63785052c9124"
+}

package/dist/skill/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: openship
+description: Work with OpenShip v1 discovery, public source snapshots, candidate code changes, and self-contained system descriptions. Use when implementing, consuming, validating, or explaining an OpenShip capability; do not use for unrelated repository or deployment work.
+---
+
+# OpenShip
+
+OpenShip lets a running project publish the source that produced it, optionally accept changes as isolated candidate versions, and optionally describe the complete software system around that source.
+
+Read only the references needed for the task:
+
+- For the protocol overview, discovery, shared conventions, or capability selection, read [references/openship.md](references/openship.md).
+- For publishing, retrieving, or validating a source snapshot, read [references/openship-sources.md](references/openship-sources.md).
+- For proposing or serving candidate code versions, read both [references/openship-sources.md](references/openship-sources.md) and [references/openship-changes.md](references/openship-changes.md).
+- For authoring or consuming a self-contained architecture and source payload, read both [references/openship-sources.md](references/openship-sources.md) and [references/openship-systems.md](references/openship-systems.md).
+
+Machine-readable schemas and conformance examples are under [references/schemas](references/schemas) and [references/examples](references/examples). Treat the Markdown specifications as normative when a constraint cannot be expressed by JSON Schema.
+

package/dist/skill/references/examples/invalid/changes-submission.json

@@ -0,0 +1,9 @@
+{
+  "openship": "1.0",
+  "capability": "changes",
+  "base": "not-a-digest",
+  "title": "",
+  "intent": "",
+  "files": {}
+}
+

package/dist/skill/references/examples/invalid/changes-violation.json

@@ -0,0 +1,7 @@
+{
+  "openship": "1.0",
+  "capability": "changes",
+  "error": "policy_violation",
+  "message": "The response forgot to identify any violation.",
+  "violations": []
+}

package/dist/skill/references/examples/invalid/discovery.json

@@ -0,0 +1,13 @@
+{
+  "openship": "1.0",
+  "capability": "discovery",
+  "project": { "name": "Broken", "description": "Sources is missing." },
+  "capabilities": {
+    "changes": {
+      "policy": "https://example.com/openship/policy.json",
+      "submit": "https://example.com/openship/changes",
+      "status": "https://example.com/openship/changes/{changeId}"
+    }
+  }
+}
+

package/dist/skill/references/examples/invalid/sources-manifest.json

@@ -0,0 +1,11 @@
+{
+  "openship": "1.0",
+  "capability": "sources",
+  "digest": "sha256:1d322539e651a3c2d7c51eb8b33160627395b9601bff909e599771b806d9e565",
+  "project": { "name": "Broken", "description": "Contains an unsafe path." },
+  "totals": { "files": 1, "bytes": 1 },
+  "files": [
+    { "path": "../secret", "size": 1, "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "encoding": "utf-8", "mediaType": "text/plain", "type": "file" }
+  ]
+}
+

package/dist/skill/references/examples/invalid/systems-ownership.json

@@ -0,0 +1,29 @@
+{
+  "openship": "1.0",
+  "capability": "systems",
+  "source": {
+    "manifest": {
+      "openship": "1.0",
+      "capability": "sources",
+      "digest": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+      "project": { "name": "Broken ownership", "description": "A Systems node with non-conformant ownership." },
+      "totals": { "files": 0, "bytes": 0 },
+      "files": []
+    },
+    "bundle": {
+      "openship": "1.0",
+      "capability": "sources",
+      "digest": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+      "files": {}
+    }
+  },
+  "system": {
+    "id": "broken-ownership",
+    "name": "Broken ownership",
+    "rootNodeId": "s.root",
+    "nodes": [
+      { "id": "s.root", "kind": "Root", "name": "Broken ownership", "metadata": { "ownership": "partner" } }
+    ],
+    "edges": []
+  }
+}

package/dist/skill/references/examples/invalid/systems.json

@@ -0,0 +1,34 @@
+{
+  "openship": "1.0",
+  "capability": "systems",
+  "source": {
+    "manifest": {
+      "openship": "1.0",
+      "capability": "sources",
+      "digest": "sha256:1d322539e651a3c2d7c51eb8b33160627395b9601bff909e599771b806d9e565",
+      "project": { "name": "Broken", "description": "The runtime edge targets a Library." },
+      "totals": { "files": 0, "bytes": 0 },
+      "files": []
+    },
+    "bundle": {
+      "openship": "1.0",
+      "capability": "sources",
+      "digest": "sha256:1d322539e651a3c2d7c51eb8b33160627395b9601bff909e599771b806d9e565",
+      "files": {}
+    }
+  },
+  "system": {
+    "id": "broken",
+    "name": "Broken",
+    "rootNodeId": "s.root",
+    "nodes": [
+      { "id": "s.root", "kind": "Root", "name": "Broken", "metadata": { "ownership": "first_party" } },
+      { "id": "h.runtime", "kind": "Host", "name": "Runtime", "parentId": "s.root", "metadata": { "ownership": "first_party" } },
+      { "id": "p.web", "kind": "Process", "name": "Web", "parentId": "h.runtime", "metadata": { "ownership": "first_party" } },
+      { "id": "l.config", "kind": "Library", "name": "Config", "metadata": { "ownership": "third_party" } }
+    ],
+    "edges": [
+      { "id": "e.invalid", "type": "Runtime", "fromNodeId": "p.web", "toNodeId": "l.config" }
+    ]
+  }
+}

package/dist/skill/references/examples/valid/changes-accepted.json

@@ -0,0 +1,13 @@
+{
+  "openship": "1.0",
+  "capability": "changes",
+  "changeId": "5d7621f4-7ad5-49f6-8168-da99620ff1cf",
+  "base": "sha256:1d322539e651a3c2d7c51eb8b33160627395b9601bff909e599771b806d9e565",
+  "digest": "sha256:b0eea548e74112b0be4dcff867f405086ef4456508089ee007ce38959a78cb08",
+  "status": "pending",
+  "phase": "queued",
+  "candidateOrigin": "https://b0eea548e741.example-builds.net",
+  "statusUrl": "https://example.com/openship/changes/5d7621f4-7ad5-49f6-8168-da99620ff1cf",
+  "buildId": "b0eea548e741"
+}
+

package/dist/skill/references/examples/valid/changes-policy.json

@@ -0,0 +1,12 @@
+{
+  "openship": "1.0",
+  "capability": "changes",
+  "writable": ["app/**", "public/**"],
+  "protected": ["app/api/**", "skills/openship/**"],
+  "limits": { "filesPerChange": 40, "bytesPerFile": 262144, "bytesPerChange": 1048576 },
+  "contentRules": [
+    { "id": "dynamic-eval", "rule": "Dynamic evaluation", "message": "Use static imports." }
+  ],
+  "document": "https://example.com/openship/file/skills/openship/references/openship-changes.md"
+}
+

package/dist/skill/references/examples/valid/changes-status.json

@@ -0,0 +1,12 @@
+{
+  "openship": "1.0",
+  "capability": "changes",
+  "changeId": "5d7621f4-7ad5-49f6-8168-da99620ff1cf",
+  "base": "sha256:1d322539e651a3c2d7c51eb8b33160627395b9601bff909e599771b806d9e565",
+  "digest": "sha256:b0eea548e74112b0be4dcff867f405086ef4456508089ee007ce38959a78cb08",
+  "status": "ready",
+  "phase": "deployed",
+  "candidateOrigin": "https://b0eea548e741.example-builds.net",
+  "reason": null
+}
+

package/dist/skill/references/examples/valid/changes-submission.json

@@ -0,0 +1,11 @@
+{
+  "openship": "1.0",
+  "capability": "changes",
+  "base": "sha256:1d322539e651a3c2d7c51eb8b33160627395b9601bff909e599771b806d9e565",
+  "title": "Update the example page",
+  "intent": "Make the example visibly identify its second candidate version.",
+  "files": {
+    "app/page.js": { "encoding": "utf-8", "content": "export default function Page(){return \"v2\"}\n" }
+  }
+}
+

package/dist/skill/references/examples/valid/changes-violation.json

@@ -0,0 +1,16 @@
+{
+  "openship": "1.0",
+  "capability": "changes",
+  "error": "policy_violation",
+  "message": "1 rule rejected this change.",
+  "base": "sha256:1d322539e651a3c2d7c51eb8b33160627395b9601bff909e599771b806d9e565",
+  "policy": "https://example.com/openship/policy.json",
+  "violations": [
+    {
+      "gate": "path",
+      "rule": "protected",
+      "path": "app/api/session/route.ts",
+      "message": "This path is protected."
+    }
+  ]
+}

package/dist/skill/references/examples/valid/discovery.json

@@ -0,0 +1,20 @@
+{
+  "openship": "1.0",
+  "capability": "discovery",
+  "project": { "name": "Example", "description": "An example OpenShip project." },
+  "skill": "https://example.com/openship/file/skills/openship/SKILL.md",
+  "capabilities": {
+    "sources": {
+      "manifest": "https://example.com/openship/manifest.json",
+      "bundle": "https://example.com/openship/bundle.json",
+      "file": "https://example.com/openship/file/{path}",
+      "archive": "https://example.com/openship/source.tar.gz"
+    },
+    "changes": {
+      "policy": "https://example.com/openship/policy.json",
+      "submit": "https://example.com/openship/changes",
+      "status": "https://example.com/openship/changes/{changeId}"
+    }
+  }
+}
+

package/dist/skill/references/examples/valid/sources-bundle.json

@@ -0,0 +1,10 @@
+{
+  "openship": "1.0",
+  "capability": "sources",
+  "digest": "sha256:1d322539e651a3c2d7c51eb8b33160627395b9601bff909e599771b806d9e565",
+  "files": {
+    "app/page.js": { "encoding": "utf-8", "content": "export default function Page() {}\n" },
+    "package.json": { "encoding": "utf-8", "content": "{\"name\":\"example\"}\n" }
+  }
+}
+

package/dist/skill/references/examples/valid/sources-manifest.json

@@ -0,0 +1,27 @@
+{
+  "openship": "1.0",
+  "capability": "sources",
+  "generatedAt": "2026-08-21T12:00:00.000Z",
+  "digest": "sha256:1d322539e651a3c2d7c51eb8b33160627395b9601bff909e599771b806d9e565",
+  "project": { "name": "Example", "description": "An example OpenShip project." },
+  "totals": { "files": 2, "bytes": 53 },
+  "files": [
+    {
+      "path": "app/page.js",
+      "size": 34,
+      "sha256": "6ce070542590adb63fd9621ff65be91446f8bd9b65465cda5e4ec43e5d86dc5e",
+      "encoding": "utf-8",
+      "mediaType": "text/plain; charset=utf-8",
+      "type": "file"
+    },
+    {
+      "path": "package.json",
+      "size": 19,
+      "sha256": "9579cf52285b23b618b615d704b19d04ff591ae513f6ae34ef37e2b9a067cb12",
+      "encoding": "utf-8",
+      "mediaType": "application/json; charset=utf-8",
+      "type": "file"
+    }
+  ]
+}
+

package/dist/skill/references/examples/valid/systems.json

@@ -0,0 +1,55 @@
+{
+  "openship": "1.0",
+  "capability": "systems",
+  "source": {
+    "manifest": {
+      "openship": "1.0",
+      "capability": "sources",
+      "digest": "sha256:1d322539e651a3c2d7c51eb8b33160627395b9601bff909e599771b806d9e565",
+      "project": { "name": "Example", "description": "An example OpenShip project." },
+      "totals": { "files": 2, "bytes": 53 },
+      "files": [
+        { "path": "app/page.js", "size": 34, "sha256": "6ce070542590adb63fd9621ff65be91446f8bd9b65465cda5e4ec43e5d86dc5e", "encoding": "utf-8", "mediaType": "text/plain; charset=utf-8", "type": "file" },
+        { "path": "package.json", "size": 19, "sha256": "9579cf52285b23b618b615d704b19d04ff591ae513f6ae34ef37e2b9a067cb12", "encoding": "utf-8", "mediaType": "application/json; charset=utf-8", "type": "file" }
+      ]
+    },
+    "bundle": {
+      "openship": "1.0",
+      "capability": "sources",
+      "digest": "sha256:1d322539e651a3c2d7c51eb8b33160627395b9601bff909e599771b806d9e565",
+      "files": {
+        "app/page.js": { "encoding": "utf-8", "content": "export default function Page() {}\n" },
+        "package.json": { "encoding": "utf-8", "content": "{\"name\":\"example\"}\n" }
+      }
+    }
+  },
+  "system": {
+    "id": "example-system",
+    "name": "Example system",
+    "rootNodeId": "s.root",
+    "nodes": [
+      { "id": "s.root", "kind": "Root", "name": "Example", "metadata": { "ownership": "first_party" } },
+      { "id": "h.runtime", "kind": "Host", "name": "Application runtime", "parentId": "s.root", "metadata": { "ownership": "first_party" } },
+      { "id": "p.web", "kind": "Process", "name": "Web process", "parentId": "h.runtime", "sourceSelectors": ["app/**"], "metadata": { "ownership": "first_party" } },
+      { "id": "l.config", "kind": "Library", "name": "Project configuration", "sourceSelectors": ["package.json"], "metadata": { "ownership": "third_party" } }
+    ],
+    "edges": [
+      { "id": "e.web.config", "type": "Dependency", "fromNodeId": "p.web", "toNodeId": "l.config" }
+    ],
+    "context": {
+      "concerns": ["Interfaces", "Implementation"],
+      "documents": [
+        { "kind": "Document", "hash": "sha256:77760f8cb9fdaaadd3c22612d97fba630f78730c8d750c6cce02754b689b11da", "title": "API contract", "language": "en", "text": "The API returns JSON." },
+        { "kind": "Skill", "hash": "sha256:bae5f866c2994c1cec740965e45935920376a2df1fb933e798c3e2c3b8c0e391", "title": "Node implementation", "language": "en", "text": "Use Node.js." },
+        { "kind": "Prompt", "hash": "sha256:416a3efe045d89a00fa0cca4516b8bdd442a8f65a42e35a5c102067f3ecb429d", "title": "System prompt", "language": "en", "text": "Keep changes minimal." }
+      ],
+      "matrix": [
+        { "nodeId": "p.web", "concern": "Interfaces", "documentRefs": ["sha256:77760f8cb9fdaaadd3c22612d97fba630f78730c8d750c6cce02754b689b11da"], "skillRefs": [] }
+      ],
+      "systemPromptRefs": ["sha256:416a3efe045d89a00fa0cca4516b8bdd442a8f65a42e35a5c102067f3ecb429d"],
+      "artifacts": [
+        { "id": "a.web.code", "nodeId": "p.web", "concern": "Implementation", "type": "Code", "sourcePaths": ["app/page.js"] }
+      ]
+    }
+  }
+}

package/dist/skill/references/openship-changes.md

@@ -0,0 +1,135 @@
+# OpenShip Changes v1
+
+OpenShip Changes lets a project accept a replacement patch against a known Sources digest and, after validation, expose the resulting code at an isolated candidate origin.
+
+Changes depends on [OpenShip Sources](openship-sources.md). It does not promote code to production.
+
+## Discovery and methods
+
+Discovery advertises:
+
+- `policy`: public `GET` describing server-specific rules.
+- `submit`: `POST` accepting a JSON change.
+- `status`: public `GET` URI template containing `{changeId}`.
+
+Policy and status reads follow OpenShip's public CORS rules. Submission MUST support CORS preflight for JSON and any advertised authorization or payment headers.
+
+## Policy
+
+```json
+{
+  "openship": "1.0",
+  "capability": "changes",
+  "writable": ["app/**", "components/**", "public/**"],
+  "protected": ["app/api/**", "skills/openship/**"],
+  "limits": {
+    "filesPerChange": 40,
+    "bytesPerFile": 262144,
+    "bytesPerChange": 1048576
+  },
+  "contentRules": [
+    { "id": "dynamic-eval", "rule": "Dynamic evaluation", "message": "Use static imports." }
+  ],
+  "document": "https://example.com/openship/file/skills/openship/references/openship-changes.md"
+}
+```
+
+`writable` is an allowlist. `protected` takes precedence. Patterns use one shared grammar: an exact path matches itself; a value ending in `/**` matches that directory and all descendants. No other wildcard syntax is defined in v1.
+
+A producer MAY add authorization, payment, media, build, review, or deployment policy. It MUST NOT describe a filter as a security boundary.
+
+See [schemas/changes-policy.schema.json](schemas/changes-policy.schema.json).
+
+## Submission
+
+```json
+{
+  "openship": "1.0",
+  "capability": "changes",
+  "base": "sha256:1c413f...",
+  "title": "Improve the project page",
+  "intent": "Explain what the change does and why.",
+  "files": {
+    "app/page.tsx": { "encoding": "utf-8", "content": "..." },
+    "public/old-logo.png": null
+  }
+}
+```
+
+`base` MUST name a Sources digest the server currently accepts. A file value replaces or creates that path. `null` deletes it. An absent path is unchanged. Paths and encodings follow Sources.
+
+The producer MUST validate the envelope, base, paths, sizes, content rules, and resulting file tree before charging or queueing expensive work. A stale base returns `409`. Deterministic policy violations return `422` with precise violations.
+
+See [schemas/changes-submission.schema.json](schemas/changes-submission.schema.json).
+
+## Accepted response
+
+```json
+{
+  "openship": "1.0",
+  "capability": "changes",
+  "changeId": "5d7621f4-7ad5-49f6-8168-da99620ff1cf",
+  "base": "sha256:1c413f...",
+  "digest": "sha256:9f2c1a...",
+  "status": "pending",
+  "phase": "queued",
+  "candidateOrigin": "https://9f2c1a7b3e04.example-builds.net",
+  "statusUrl": "https://example.com/openship/changes/5d7621f4-7ad5-49f6-8168-da99620ff1cf",
+  "buildId": "9f2c1a7b3e04"
+}
+```
+
+The server computes the resulting Manifest and digest before acceptance. `candidateOrigin` MUST be returned for an accepted change, even if it is not live yet. `buildId` and `phase` are optional provider metadata.
+
+The same resulting digest MAY return an existing record with `200`. A newly queued change returns `202`.
+
+See [schemas/changes-accepted.schema.json](schemas/changes-accepted.schema.json).
+
+## Status
+
+The normative lifecycle is:
+
+| Status | Meaning |
+|---|---|
+| `pending` | Accepted but processing has not started. |
+| `processing` | Validation, building, review, or publication is in progress. |
+| `ready` | Candidate origin is live and verified. |
+| `rejected` | Policy or review rejected the candidate. |
+| `failed` | Infrastructure failed to produce a candidate. |
+
+An implementation maps internal states such as `queued`, `building`, `reviewing`, and `deployed` into the core status and MAY expose the internal value as `phase`.
+
+Before reporting `ready`, the producer MUST fetch or otherwise verify the candidate origin's advertised Sources Manifest and confirm its digest equals the accepted resulting digest.
+
+Status responses MUST use `Cache-Control: no-store`. See [schemas/changes-status.schema.json](schemas/changes-status.schema.json).
+
+## Error responses
+
+Errors contain `openship`, `capability`, `error`, and a human-readable `message`. Relevant status codes include:
+
+- `400` malformed JSON or envelope.
+- `401` or `403` authorization failure.
+- `402` advertised payment required.
+- `409` stale or unknown base digest.
+- `413` transport or decoded size limit.
+- `422` deterministic policy violations, with `violations`.
+- `501` Changes is installed but disabled on this deployment.
+
+Synchronous stale-base and policy-violation responses follow
+[schemas/changes-violation.schema.json](schemas/changes-violation.schema.json).
+
+## Candidate isolation
+
+A candidate executes code supplied by an untrusted author. Therefore:
+
+- Its origin MUST use a different registrable domain from production, not merely a subdomain.
+- Its build and runtime MUST contain no production secret or production credential.
+- Submitted code MUST never receive a deployment credential.
+- Build execution SHOULD have no network after dependency installation and SHOULD use explicit resource limits.
+- Production promotion is a separate maintainer decision outside OpenShip.
+
+Path filters, content scans, tests, and model review are useful filters. Isolation is the security boundary.
+
+## Identity and lineage
+
+The resulting Sources digest is the candidate's normative identity. A hostname or `buildId` derived from a digest is a convenience that clients verify by retrieving Sources from the candidate origin. Candidate Sources SHOULD include optional `parent` metadata naming the base digest.