@agentproto/corpus-cli 0.1.0-alpha.1 → 0.1.0-alpha.3

package/dist/index.d.ts

@@ -1,10 +1,6 @@
 export { N as NodeFsAdapter, a as NodeFsAdapterOptions, O as OsIdentityAdapter, b as OsIdentityAdapterOptions } from './os-identity.adapter-CLBmnRoD.js';
 import '@agentproto/corpus';
 
-/**
- * Version constant — pinned at build time. Stay in sync with
- * package.json manually until we wire a build-time inliner.
- */
-declare const VERSION: "0.1.0-alpha.0";
+declare const VERSION: string;
 
 export { VERSION };

package/dist/index.mjs

@@ -1,7 +1,8 @@
+import { readFileSync, existsSync } from 'fs';
+import path, { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
 import { randomBytes } from 'crypto';
 import { stat, readFile, mkdir, writeFile, rename, appendFile, readdir, rm } from 'fs/promises';
-import path from 'path';
-import { existsSync } from 'fs';
 import os from 'os';
 
 /**
@@ -9,8 +10,18 @@ import os from 'os';
  * The `corpus` binary — local-topology host for AIP-10 corpora.
  */
 
-// src/version.ts
-var VERSION = "0.1.0-alpha.0";
+function readVersion() {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(
+      readFileSync(resolve(here, "../package.json"), "utf8")
+    );
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+var VERSION = readVersion();
 var NodeFsAdapter = class {
   root;
   constructor(opts) {

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/version.ts","../src/ports/local-fs.adapter.ts","../src/ports/os-identity.adapter.ts"],"names":["path"],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * Version constant — pinned at build time. Stay in sync with\n * package.json manually until we wire a build-time inliner.\n */\nexport const VERSION = \"0.1.0-alpha.0\" as const\n","/**\n * NodeFsAdapter — `FsPort` implementation backed by node:fs.\n *\n * Atomic writes via temp + rename (the same posix pattern every\n * mature tool uses). Recursive `walk` skips hidden segments\n * (anything beginning with `.`). Advisory locks via lockfiles in\n * `.corpus-locks/` next to the target — single-process safe; for\n * multi-process the lockfile owner pid is recorded so callers can\n * see who holds the lock.\n */\n\nimport { randomBytes } from \"node:crypto\"\nimport {\n  appendFile,\n  mkdir,\n  readFile,\n  readdir,\n  rename,\n  rm,\n  stat,\n  writeFile,\n} from \"node:fs/promises\"\nimport path from \"node:path\"\nimport { existsSync } from \"node:fs\"\nimport type {\n  FsPort,\n  FsLockHandle,\n  FsStat,\n} from \"@agentproto/corpus\"\n\nexport interface NodeFsAdapterOptions {\n  /**\n   * Absolute path to the workspace root. All FsPort paths are\n   * resolved relative to this — the kit never sees host filesystem\n   * paths.\n   */\n  readonly root: string\n}\n\nexport class NodeFsAdapter implements FsPort {\n  private readonly root: string\n\n  constructor(opts: NodeFsAdapterOptions) {\n    this.root = opts.root\n  }\n\n  async exists(p: string): Promise<boolean> {\n    try {\n      await stat(this.resolve(p))\n      return true\n    } catch {\n      return false\n    }\n  }\n\n  async readFile(p: string): Promise<string> {\n    return await readFile(this.resolve(p), \"utf8\")\n  }\n\n  /**\n   * Atomic write: write to `${target}.tmp-{nonce}`, fsync, rename.\n   * Rename is atomic on the same filesystem. Creates parent dirs as\n   * needed (most callers expect mkdir -p semantics).\n   */\n  async writeFile(p: string, content: string): Promise<void> {\n    const target = this.resolve(p)\n    await mkdir(path.dirname(target), { recursive: true })\n    const tmp = `${target}.tmp-${randomBytes(8).toString(\"hex\")}`\n    await writeFile(tmp, content, \"utf8\")\n    await rename(tmp, target)\n  }\n\n  async appendFile(p: string, content: string): Promise<void> {\n    const target = this.resolve(p)\n    await mkdir(path.dirname(target), { recursive: true })\n    await appendFile(target, content, \"utf8\")\n  }\n\n  async readdir(p: string): Promise<readonly string[]> {\n    const target = this.resolve(p)\n    const entries = await readdir(target)\n    return entries\n  }\n\n  async walk(p: string): Promise<readonly string[]> {\n    const out: string[] = []\n    const start = this.resolve(p)\n    const rootForRelative = start\n    const visit = async (dir: string): Promise<void> => {\n      let entries: string[] = []\n      try {\n        entries = await readdir(dir)\n      } catch {\n        return\n      }\n      for (const ent of entries) {\n        // Skip hidden segments — matches the FsPort contract.\n        if (ent.startsWith(\".\")) continue\n        const full = path.join(dir, ent)\n        const s = await stat(full)\n        if (s.isDirectory()) {\n          await visit(full)\n        } else if (s.isFile()) {\n          const rel = path.relative(rootForRelative, full).split(path.sep).join(\"/\")\n          out.push(rel)\n        }\n      }\n    }\n    await visit(start)\n    return out\n  }\n\n  async stat(p: string): Promise<FsStat | null> {\n    try {\n      const s = await stat(this.resolve(p))\n      return {\n        kind: s.isDirectory() ? \"directory\" : \"file\",\n        bytes: s.isFile() ? s.size : undefined,\n        modifiedAt: s.mtime,\n      }\n    } catch {\n      return null\n    }\n  }\n\n  /**\n   * Advisory lock via a lockfile. Spins waiting for the lockfile to\n   * disappear, then creates it with exclusive flag. Released by\n   * deleting it. Single-process safe; multi-process semi-safe (the\n   * write is best-effort exclusive — adequate for the corpus's\n   * promote-entry transaction which is rare and short-lived).\n   */\n  async lock(p: string): Promise<FsLockHandle> {\n    const target = this.resolve(p)\n    const lockDir = path.join(path.dirname(target), \".corpus-locks\")\n    await mkdir(lockDir, { recursive: true })\n    const lockFile = path.join(lockDir, path.basename(target) + \".lock\")\n    const myToken = `${process.pid}-${randomBytes(4).toString(\"hex\")}`\n\n    // Spin until we acquire. Cheap polling is fine for corpus\n    // workloads — transactions are < 1s.\n    while (true) {\n      if (!existsSync(lockFile)) {\n        try {\n          await writeFile(lockFile, myToken, { encoding: \"utf8\", flag: \"wx\" })\n          // Race: verify our token is the one that landed.\n          const written = await readFile(lockFile, \"utf8\").catch(() => \"\")\n          if (written === myToken) break\n        } catch {\n          // Lost the race — fall through and retry.\n        }\n      }\n      await new Promise((r) => setTimeout(r, 25))\n    }\n    return {\n      release: async () => {\n        try {\n          await rm(lockFile, { force: true })\n        } catch {\n          // Lockfile already gone — no-op.\n        }\n      },\n    }\n  }\n\n  // ── Helpers ────────────────────────────────────────────────────\n\n  /**\n   * Resolve a workspace-relative path to an absolute host path.\n   * Refuses to climb out of the workspace root (defense against\n   * `../../etc/passwd`-style abuse) — the corpus kit's paths must\n   * stay inside the workspace.\n   */\n  private resolve(p: string): string {\n    const normalized = path.posix.normalize(\"/\" + p.replace(/^\\/+/, \"\"))\n    // Drop the leading \"/\" so path.join joins correctly under root.\n    const rel = normalized.slice(1)\n    if (rel.startsWith(\"..\")) {\n      throw new Error(\n        `NodeFsAdapter: path \"${p}\" escapes the workspace root \"${this.root}\"`\n      )\n    }\n    return path.join(this.root, rel)\n  }\n}\n","/**\n * OsIdentityAdapter — `IdentityPort` resolved from OS user + cwd.\n *\n * Local-topology identity model:\n *   - principal      = `ws://users/{os-user}`\n *   - identityTree   = [\n *       `ws://users/{os-user}`,\n *       `ws://workspaces/{workspace-dir-name}`,\n *     ]\n *\n * Roles + guilds + orgs don't exist locally — single-user, single-\n * workspace machine. Scope-policy in the corpus adapter matches\n * against this minimal tree, so AIP-10 `appliesTo` entries scoped\n * narrower than `ws://users/...` or `ws://workspaces/...` are\n * invisible to the local user. That's the intended local-topology\n * semantics: you only see what's scoped to you or your workspace.\n */\n\nimport os from \"node:os\"\nimport path from \"node:path\"\nimport type {\n  CallerIdentity,\n  IdentityPort,\n} from \"@agentproto/corpus\"\n\nexport interface OsIdentityAdapterOptions {\n  readonly workspaceRoot: string\n  /** Override the OS user (useful for tests). Falls back to os.userInfo(). */\n  readonly userOverride?: string\n}\n\nexport class OsIdentityAdapter implements IdentityPort {\n  private readonly cached: CallerIdentity\n\n  constructor(opts: OsIdentityAdapterOptions) {\n    // Env vars win over os.userInfo() — matches Unix convention (env is\n    // explicit intent, OS detection is fallback). Also keeps tests\n    // deterministic across CI environments where the OS user differs.\n    const user =\n      opts.userOverride ??\n      process.env.USER ??\n      process.env.USERNAME ??\n      safeGetUser() ??\n      \"anonymous\"\n    const wsName = path.basename(opts.workspaceRoot) || \"default\"\n    this.cached = Object.freeze({\n      principal: `ws://users/${slugify(user)}`,\n      identityTree: Object.freeze([\n        `ws://users/${slugify(user)}`,\n        `ws://workspaces/${slugify(wsName)}`,\n      ]),\n      displayName: user,\n    })\n  }\n\n  async resolve(): Promise<CallerIdentity> {\n    return this.cached\n  }\n}\n\nfunction safeGetUser(): string | undefined {\n  try {\n    return os.userInfo().username\n  } catch {\n    return undefined\n  }\n}\n\nfunction slugify(s: string): string {\n  return s\n    .toLowerCase()\n    .replace(/[^a-z0-9-]+/g, \"-\")\n    .replace(/^-+|-+$/g, \"\")\n    .replace(/-{2,}/g, \"-\")\n    .slice(0, 64) || \"anonymous\"\n}\n"]}
+{"version":3,"sources":["../src/version.ts","../src/ports/local-fs.adapter.ts","../src/ports/os-identity.adapter.ts"],"names":["path"],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * CLI version — derived from the package's own package.json at runtime,\n * so it never drifts from the published version on a release bump.\n *\n * `import.meta.url` resolves to dist/cli.mjs in the published bundle and\n * to src/version.ts under tsx/vitest; in both, package.json sits one\n * directory up. A defensive fallback keeps --version from ever throwing.\n */\nimport { readFileSync } from \"node:fs\"\nimport { dirname, resolve } from \"node:path\"\nimport { fileURLToPath } from \"node:url\"\n\nfunction readVersion(): string {\n  try {\n    const here = dirname(fileURLToPath(import.meta.url))\n    const pkg = JSON.parse(\n      readFileSync(resolve(here, \"../package.json\"), \"utf8\")\n    ) as { version?: string }\n    return pkg.version ?? \"0.0.0\"\n  } catch {\n    return \"0.0.0\"\n  }\n}\n\nexport const VERSION: string = readVersion()\n","/**\n * NodeFsAdapter — `FsPort` implementation backed by node:fs.\n *\n * Atomic writes via temp + rename (the same posix pattern every\n * mature tool uses). Recursive `walk` skips hidden segments\n * (anything beginning with `.`). Advisory locks via lockfiles in\n * `.corpus-locks/` next to the target — single-process safe; for\n * multi-process the lockfile owner pid is recorded so callers can\n * see who holds the lock.\n */\n\nimport { randomBytes } from \"node:crypto\"\nimport {\n  appendFile,\n  mkdir,\n  readFile,\n  readdir,\n  rename,\n  rm,\n  stat,\n  writeFile,\n} from \"node:fs/promises\"\nimport path from \"node:path\"\nimport { existsSync } from \"node:fs\"\nimport type {\n  FsPort,\n  FsLockHandle,\n  FsStat,\n} from \"@agentproto/corpus\"\n\nexport interface NodeFsAdapterOptions {\n  /**\n   * Absolute path to the workspace root. All FsPort paths are\n   * resolved relative to this — the kit never sees host filesystem\n   * paths.\n   */\n  readonly root: string\n}\n\nexport class NodeFsAdapter implements FsPort {\n  private readonly root: string\n\n  constructor(opts: NodeFsAdapterOptions) {\n    this.root = opts.root\n  }\n\n  async exists(p: string): Promise<boolean> {\n    try {\n      await stat(this.resolve(p))\n      return true\n    } catch {\n      return false\n    }\n  }\n\n  async readFile(p: string): Promise<string> {\n    return await readFile(this.resolve(p), \"utf8\")\n  }\n\n  /**\n   * Atomic write: write to `${target}.tmp-{nonce}`, fsync, rename.\n   * Rename is atomic on the same filesystem. Creates parent dirs as\n   * needed (most callers expect mkdir -p semantics).\n   */\n  async writeFile(p: string, content: string): Promise<void> {\n    const target = this.resolve(p)\n    await mkdir(path.dirname(target), { recursive: true })\n    const tmp = `${target}.tmp-${randomBytes(8).toString(\"hex\")}`\n    await writeFile(tmp, content, \"utf8\")\n    await rename(tmp, target)\n  }\n\n  async appendFile(p: string, content: string): Promise<void> {\n    const target = this.resolve(p)\n    await mkdir(path.dirname(target), { recursive: true })\n    await appendFile(target, content, \"utf8\")\n  }\n\n  async readdir(p: string): Promise<readonly string[]> {\n    const target = this.resolve(p)\n    const entries = await readdir(target)\n    return entries\n  }\n\n  async walk(p: string): Promise<readonly string[]> {\n    const out: string[] = []\n    const start = this.resolve(p)\n    const rootForRelative = start\n    const visit = async (dir: string): Promise<void> => {\n      let entries: string[] = []\n      try {\n        entries = await readdir(dir)\n      } catch {\n        return\n      }\n      for (const ent of entries) {\n        // Skip hidden segments — matches the FsPort contract.\n        if (ent.startsWith(\".\")) continue\n        const full = path.join(dir, ent)\n        const s = await stat(full)\n        if (s.isDirectory()) {\n          await visit(full)\n        } else if (s.isFile()) {\n          const rel = path.relative(rootForRelative, full).split(path.sep).join(\"/\")\n          out.push(rel)\n        }\n      }\n    }\n    await visit(start)\n    return out\n  }\n\n  async stat(p: string): Promise<FsStat | null> {\n    try {\n      const s = await stat(this.resolve(p))\n      return {\n        kind: s.isDirectory() ? \"directory\" : \"file\",\n        bytes: s.isFile() ? s.size : undefined,\n        modifiedAt: s.mtime,\n      }\n    } catch {\n      return null\n    }\n  }\n\n  /**\n   * Advisory lock via a lockfile. Spins waiting for the lockfile to\n   * disappear, then creates it with exclusive flag. Released by\n   * deleting it. Single-process safe; multi-process semi-safe (the\n   * write is best-effort exclusive — adequate for the corpus's\n   * promote-entry transaction which is rare and short-lived).\n   */\n  async lock(p: string): Promise<FsLockHandle> {\n    const target = this.resolve(p)\n    const lockDir = path.join(path.dirname(target), \".corpus-locks\")\n    await mkdir(lockDir, { recursive: true })\n    const lockFile = path.join(lockDir, path.basename(target) + \".lock\")\n    const myToken = `${process.pid}-${randomBytes(4).toString(\"hex\")}`\n\n    // Spin until we acquire. Cheap polling is fine for corpus\n    // workloads — transactions are < 1s.\n    while (true) {\n      if (!existsSync(lockFile)) {\n        try {\n          await writeFile(lockFile, myToken, { encoding: \"utf8\", flag: \"wx\" })\n          // Race: verify our token is the one that landed.\n          const written = await readFile(lockFile, \"utf8\").catch(() => \"\")\n          if (written === myToken) break\n        } catch {\n          // Lost the race — fall through and retry.\n        }\n      }\n      await new Promise((r) => setTimeout(r, 25))\n    }\n    return {\n      release: async () => {\n        try {\n          await rm(lockFile, { force: true })\n        } catch {\n          // Lockfile already gone — no-op.\n        }\n      },\n    }\n  }\n\n  // ── Helpers ────────────────────────────────────────────────────\n\n  /**\n   * Resolve a workspace-relative path to an absolute host path.\n   * Refuses to climb out of the workspace root (defense against\n   * `../../etc/passwd`-style abuse) — the corpus kit's paths must\n   * stay inside the workspace.\n   */\n  private resolve(p: string): string {\n    const normalized = path.posix.normalize(\"/\" + p.replace(/^\\/+/, \"\"))\n    // Drop the leading \"/\" so path.join joins correctly under root.\n    const rel = normalized.slice(1)\n    if (rel.startsWith(\"..\")) {\n      throw new Error(\n        `NodeFsAdapter: path \"${p}\" escapes the workspace root \"${this.root}\"`\n      )\n    }\n    return path.join(this.root, rel)\n  }\n}\n","/**\n * OsIdentityAdapter — `IdentityPort` resolved from OS user + cwd.\n *\n * Local-topology identity model:\n *   - principal      = `ws://users/{os-user}`\n *   - identityTree   = [\n *       `ws://users/{os-user}`,\n *       `ws://workspaces/{workspace-dir-name}`,\n *     ]\n *\n * Roles + guilds + orgs don't exist locally — single-user, single-\n * workspace machine. Scope-policy in the corpus adapter matches\n * against this minimal tree, so AIP-10 `appliesTo` entries scoped\n * narrower than `ws://users/...` or `ws://workspaces/...` are\n * invisible to the local user. That's the intended local-topology\n * semantics: you only see what's scoped to you or your workspace.\n */\n\nimport os from \"node:os\"\nimport path from \"node:path\"\nimport type {\n  CallerIdentity,\n  IdentityPort,\n} from \"@agentproto/corpus\"\n\nexport interface OsIdentityAdapterOptions {\n  readonly workspaceRoot: string\n  /** Override the OS user (useful for tests). Falls back to os.userInfo(). */\n  readonly userOverride?: string\n}\n\nexport class OsIdentityAdapter implements IdentityPort {\n  private readonly cached: CallerIdentity\n\n  constructor(opts: OsIdentityAdapterOptions) {\n    // Env vars win over os.userInfo() — matches Unix convention (env is\n    // explicit intent, OS detection is fallback). Also keeps tests\n    // deterministic across CI environments where the OS user differs.\n    const user =\n      opts.userOverride ??\n      process.env.USER ??\n      process.env.USERNAME ??\n      safeGetUser() ??\n      \"anonymous\"\n    const wsName = path.basename(opts.workspaceRoot) || \"default\"\n    this.cached = Object.freeze({\n      principal: `ws://users/${slugify(user)}`,\n      identityTree: Object.freeze([\n        `ws://users/${slugify(user)}`,\n        `ws://workspaces/${slugify(wsName)}`,\n      ]),\n      displayName: user,\n    })\n  }\n\n  async resolve(): Promise<CallerIdentity> {\n    return this.cached\n  }\n}\n\nfunction safeGetUser(): string | undefined {\n  try {\n    return os.userInfo().username\n  } catch {\n    return undefined\n  }\n}\n\nfunction slugify(s: string): string {\n  return s\n    .toLowerCase()\n    .replace(/[^a-z0-9-]+/g, \"-\")\n    .replace(/^-+|-+$/g, \"\")\n    .replace(/-{2,}/g, \"-\")\n    .slice(0, 64) || \"anonymous\"\n}\n"]}

package/dist/specs/resources/aip-10/draft/KNOWLEDGE.schema.json

@@ -0,0 +1,457 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentproto.sh/schemas/aip-10/KNOWLEDGE.schema.json",
+  "title": "agentknowledge/v1 frontmatter (AIP-10)",
+  "description": "Validates the YAML frontmatter portion of an AIP-10 entry, source, or workspace manifest. The doctype is selected via the `schema` discriminator: 'knowledge.entry/v1' (curated, mutable), 'knowledge.source/v1' (raw, immutable), or 'knowledge.workspace/v1' (workspace manifest or per-context view).",
+  "oneOf": [
+    { "$ref": "#/$defs/entry" },
+    { "$ref": "#/$defs/source" },
+    { "$ref": "#/$defs/workspace" }
+  ],
+  "$defs": {
+    "entry": {
+      "type": "object",
+      "required": ["schema", "slug", "kind", "title", "updated_at"],
+      "additionalProperties": false,
+      "properties": {
+        "schema": {
+          "const": "knowledge.entry/v1",
+          "description": "Discriminator for curated wiki entries. Mutable doctype."
+        },
+        "slug": {
+          "type": "string",
+          "minLength": 2,
+          "maxLength": 96,
+          "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$",
+          "description": "Stable kebab-case identifier. Used as the wikilink target ([[slug]]) and as the entry's path stem."
+        },
+        "kind": {
+          "type": "string",
+          "minLength": 2,
+          "maxLength": 32,
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "Entry kind. The wiki's KNOWLEDGE.md (entityTypes) and AGENTS.md schema together define the allowed values; common ones are 'entity', 'concept', 'summary', 'comparison', 'timeline'."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "description": "Human-readable page title."
+        },
+        "sources": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 2,
+            "maxLength": 96,
+            "pattern": "^[a-z0-9][a-z0-9-]*$",
+            "description": "Source id (NOT path). The host resolves ids against the source registry."
+          },
+          "default": [],
+          "description": "Provenance — list of source ids that back the claims in this entry's body."
+        },
+        "confidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "default": 1.0,
+          "description": "Curation agent's confidence in the entry's claims. Advisory; downstream consumers may weight it against source authority and recency."
+        },
+        "updated_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp of the last patch to this entry. MUST be set on every write."
+        },
+        "supersedes": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
+          },
+          "default": [],
+          "description": "Slugs of earlier entries that this one replaces. Resolution rules live in the wiki's KNOWLEDGE.md curation.conflictResolution policy."
+        },
+        "contradicts": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
+          },
+          "default": [],
+          "description": "Slugs of entries whose claims conflict with this one and that the contradiction policy could not auto-resolve. Surfaces in lint."
+        },
+        "links": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
+          },
+          "default": [],
+          "description": "OPTIONAL hint to the link resolver — slugs this entry links to. The resolver also walks the body for [[slug]] and markdown links; this field is for entries whose links are computed."
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+          },
+          "default": [],
+          "description": "Free-form tags; consumed by retrieval, search, and grouping in _index.md."
+        },
+        "metadata": {
+          "type": "object",
+          "additionalProperties": true,
+          "default": {},
+          "description": "Vendor-specific extensions. Hosts MUST tolerate unknown keys; the spec's normative fields MUST NOT change meaning."
+        }
+      }
+    },
+    "source": {
+      "type": "object",
+      "required": [
+        "schema",
+        "id",
+        "path",
+        "title",
+        "captured_at",
+        "content_hash"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "schema": {
+          "const": "knowledge.source/v1",
+          "description": "Discriminator for raw sources. Immutable doctype — once registered, the host MUST refuse mutations to the file's bytes."
+        },
+        "id": {
+          "type": "string",
+          "minLength": 2,
+          "maxLength": 96,
+          "pattern": "^[a-z0-9][a-z0-9-]*$",
+          "description": "Stable kebab-case source id, ISO-prefixed when possible (e.g. '2026-04-27-investor-call'). Entries reference sources by id, never by path."
+        },
+        "path": {
+          "type": "string",
+          "pattern": "^sources/",
+          "description": "Path to the raw bytes, relative to the wiki root. MUST start with 'sources/'. The host pins this file once defineSource succeeds."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "description": "Human-readable source title."
+        },
+        "captured_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp of when the source entered the wiki."
+        },
+        "captured_by": {
+          "type": "string",
+          "maxLength": 200,
+          "description": "OPTIONAL — author or operator who pinned the source. May be a user identifier, an agent id, or an upstream system name."
+        },
+        "content_hash": {
+          "type": "string",
+          "pattern": "^(sha256|sha512|blake3):[A-Fa-f0-9]+$",
+          "description": "Cryptographic hash of the file bytes. sha256 is required by the spec; other algorithms MAY appear in additional sidecar fields. Once set, the file is pinned."
+        },
+        "authority": {
+          "enum": ["primary", "secondary", "rumour"],
+          "default": "secondary",
+          "description": "Source authority class. 'primary' = first-party document or recording; 'secondary' = derived analysis; 'rumour' = unverified claim. Consumed by contradiction policy."
+        },
+        "language": {
+          "type": "string",
+          "pattern": "^[a-z]{2}(-[A-Z]{2})?$",
+          "description": "OPTIONAL — BCP-47 language code of the source. Useful for ingest pipelines that pick a translator."
+        },
+        "superseded_by": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9-]*$",
+          "description": "OPTIONAL — id of a newer source that replaces this one. The host writes this; agents do not edit the source file's bytes to 'correct' it. Tombstones the source for contradiction-policy purposes while preserving the original bytes."
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+          },
+          "default": []
+        },
+        "metadata": {
+          "type": "object",
+          "additionalProperties": true,
+          "default": {},
+          "description": "Vendor-specific extensions. Hosts MUST tolerate unknown keys."
+        }
+      }
+    },
+    "workspace": {
+      "type": "object",
+      "required": ["schema", "name", "title", "description", "version"],
+      "additionalProperties": false,
+      "description": "Workspace manifest doctype. Used both as the root manifest of a wiki (no `extends`) and as a per-consumer view (with `extends`). The same schema validates both modes; the host distinguishes by checking whether `extends` is set.",
+      "properties": {
+        "schema": {
+          "const": "knowledge.workspace/v1",
+          "description": "Discriminator for the workspace manifest doctype."
+        },
+        "name": {
+          "type": "string",
+          "minLength": 2,
+          "maxLength": 96,
+          "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$",
+          "description": "Stable kebab-case identifier for the workspace or view."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "description": "Human-readable workspace title."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2000,
+          "description": "One-paragraph statement of purpose: what this workspace (or view) is for and who uses it."
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(-[A-Za-z0-9.-]+)?$",
+          "description": "Semantic version of the WORKSPACE shape. Bump on entityTypes / lints / source / curation changes. Independent of the wiki's content version."
+        },
+        "extends": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512,
+          "pattern": "^(\\.\\./|\\./)[^\\s]+/KNOWLEDGE\\.md$",
+          "description": "OPTIONAL — relative path to a parent KNOWLEDGE.md. Presence of this field makes the manifest a VIEW; absence makes it a WORKSPACE ROOT. Recursive composition: parents may themselves declare `extends`. Maximum chain depth is 8."
+        },
+        "appliesTo": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(ws://(operators|companies|skills)/[a-z][a-z0-9-]*|\\.\\./[^\\s]+)$",
+            "description": "Either a ws:// ref to an AIP-9 operator / AIP-6 company / AIP-3 skill, or a relative path to a consumer workspace folder."
+          },
+          "uniqueItems": true,
+          "description": "OPTIONAL — list of consumers this VIEW adapts the workspace for. Hosts MUST refuse the view if any binding does not resolve. Not inherited; views declare their own scope."
+        },
+        "curator": {
+          "type": "string",
+          "pattern": "^ws://operators/[a-z][a-z0-9-]*$",
+          "description": "OPTIONAL — AIP-9 operator that curates this workspace. The host activates this operator for ingest, curation, and lint passes."
+        },
+        "governance": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512,
+          "description": "OPTIONAL — AIP-7 policy or audit binding. May be a path to an AIP-7 policy file or a ws:// ref. Schema-poisoning mitigations and source-mutation audits flow through this ref."
+        },
+        "entityTypes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name"],
+            "additionalProperties": false,
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[A-Z][A-Za-z0-9]*$",
+                "description": "PascalCase type name. Merge key when composing with extends parent."
+              },
+              "fields": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "pattern": "^[a-z][A-Za-z0-9_]*$"
+                },
+                "default": [],
+                "description": "Canonical fields for this entity type. Child views append fields to parent's set."
+              },
+              "icon": {
+                "type": "string",
+                "maxLength": 8,
+                "description": "OPTIONAL — display hint, typically a single emoji."
+              },
+              "description": {
+                "type": "string",
+                "maxLength": 1000,
+                "description": "OPTIONAL — prose describing what entries of this type capture."
+              },
+              "parent": {
+                "type": "string",
+                "pattern": "^[A-Z][A-Za-z0-9]*$",
+                "description": "OPTIONAL — name of another LOCAL entity type that this one extends. Used for subtyping (e.g. Investor extends Person)."
+              }
+            }
+          },
+          "default": [],
+          "description": "Entity types this workspace recognizes. Merge-by-name against the extends parent: a child entry with the same name replaces the parent's; new names are appended."
+        },
+        "lints": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "kind", "appliesTo", "severity"],
+            "additionalProperties": false,
+            "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9-]*$",
+                "description": "Stable kebab-case lint id. Merge key when composing with extends parent."
+              },
+              "kind": {
+                "enum": [
+                  "require-source",
+                  "max-age",
+                  "min-confidence",
+                  "broken-ref",
+                  "orphan",
+                  "custom"
+                ],
+                "description": "Lint algorithm. 'custom' delegates to a host-defined check identified by `id`."
+              },
+              "appliesTo": {
+                "type": "string",
+                "pattern": "^([A-Z][A-Za-z0-9]*|\\*)$",
+                "description": "Entity type name (e.g. 'Concept') or '*' for all entries."
+              },
+              "severity": {
+                "enum": ["error", "warn", "info"],
+                "description": "Lint severity. Child views may soften (warn -> info) but governance policies may forbid that."
+              },
+              "params": {
+                "type": "object",
+                "additionalProperties": true,
+                "default": {},
+                "description": "Kind-specific parameters. e.g. { days: 90 } for 'max-age'; { min: 0.6 } for 'min-confidence'."
+              }
+            }
+          },
+          "default": [],
+          "description": "Lint rules. Merge-by-id against the extends parent: a child entry with the same id replaces the parent's; new ids are appended."
+        },
+        "sources": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "retention": {
+              "type": "string",
+              "pattern": "^(forever|days:[0-9]+)$",
+              "description": "Source retention. 'forever' (default) or 'days:<n>' for time-limited."
+            },
+            "signing": {
+              "enum": ["required", "optional", "none"],
+              "description": "Whether sources must carry an AIP-7 signature. Composes with AIP-7 governance."
+            },
+            "hashAlgo": {
+              "enum": ["sha256", "sha512", "blake3"],
+              "description": "Default content-hash algorithm for new sources."
+            },
+            "authorityDefault": {
+              "enum": ["primary", "secondary", "rumour"],
+              "description": "Default authority assigned to new sources when defineSource omits the field."
+            }
+          },
+          "description": "Source registry policy. Each leaf field overrides independently across the extends chain."
+        },
+        "curation": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "tone": {
+              "type": "string",
+              "maxLength": 200,
+              "description": "Free-form tone hint for the curator agent (e.g. 'academic', 'sales', 'neutral')."
+            },
+            "depth": {
+              "enum": ["shallow", "medium", "deep"],
+              "description": "How exhaustive the curator agent should be when distilling sources into entries."
+            },
+            "autoLink": {
+              "enum": ["byName", "manual", "off"],
+              "description": "Auto-linking policy: 'byName' walks bodies for entity names and inserts wikilinks; 'manual' leaves links to the agent; 'off' disables auto-linking entirely."
+            },
+            "conflictResolution": {
+              "enum": [
+                "defer",
+                "recency",
+                "authority",
+                "observation-count",
+                "keep-both"
+              ],
+              "description": "How the curator agent resolves contradictions when sources disagree."
+            },
+            "newEntryThreshold": {
+              "type": "string",
+              "maxLength": 1000,
+              "description": "Prose hint for when to promote a mention into a full entry (vs leaving it as a body reference)."
+            }
+          },
+          "description": "Curation policy. Each leaf field overrides independently across the extends chain."
+        },
+        "queryHints": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "preferRecent": {
+              "type": "boolean",
+              "description": "When ranking results, weight recency higher."
+            },
+            "preferAuthoritative": {
+              "type": "boolean",
+              "description": "When ranking results, weight authority='primary' higher."
+            },
+            "scopeTo": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[A-Z][A-Za-z0-9]*$"
+              },
+              "uniqueItems": true,
+              "description": "Default query scope — entity types this view focuses on. Replaced wholesale by child if present."
+            }
+          },
+          "description": "Hints for how consumers should retrieve from this view."
+        },
+        "display": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "homePage": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$",
+              "description": "OPTIONAL — slug of the entry to use as the workspace landing page."
+            },
+            "defaultGrouping": {
+              "enum": ["kind", "tag", "source"],
+              "description": "Default _index.md grouping."
+            }
+          },
+          "description": "Display hints for UIs that render the workspace. Runtime-agnostic."
+        },
+        "metadata": {
+          "type": "object",
+          "additionalProperties": true,
+          "default": {},
+          "description": "Vendor-specific extensions, namespaced under <vendor>. Deep-merged across the extends chain."
+        }
+      },
+      "allOf": [
+        {
+          "description": "A view (any manifest with appliesTo set) MUST extend a parent. A workspace-root manifest has neither field.",
+          "if": {
+            "required": ["appliesTo"],
+            "properties": {
+              "appliesTo": { "type": "array", "minItems": 1 }
+            }
+          },
+          "then": {
+            "required": ["extends"]
+          }
+        }
+      ]
+    }
+  }
+}