@agenticprimitives/devkit 0.0.0-alpha.2 → 0.0.0-alpha.21

package/dist/upgrade.js

@@ -1,13 +1,85 @@
-// `ap upgrade --canary | --pin <version|tag>` — spec 399 §3.1 / §5.2. Rewrites every @agenticprimitives/* dependency
+// `ap upgrade --canary | --pin <version|tag|newest>` — spec 399 §3.1 / §5.2. Rewrites every @agenticprimitives/* dependency
 // across the workspace manifests to ONE coherent exact set, then the caller installs, dedupes and runs doctor.
 // Planning is pure over an injected resolver; applying writes manifests and the lock. Stopping for review when a
-// contract's authority or effects change (398 §10.3) is NOT implemented in W0 — see CLAUDE.md, it is named there.
+// contract's authority or effects change (398 §10.3) is `src/definitions.ts` + the CLI's definitions review, G3.
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { DevkitError, ERROR_CODES } from './errors.js';
 import { readLock, writeLock } from './lock.js';
 import { workspaceManifests } from './workspace.js';
+export const npmVersions = async (pkg) => {
+    try {
+        const out = execFileSync('npm', ['view', pkg, 'versions', '--json'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+        const v = JSON.parse(out);
+        return Array.isArray(v) ? v : [v];
+    }
+    catch (e) {
+        throw new DevkitError(ERROR_CODES.E_RESOLVE, `npm view ${pkg} versions failed: ${e.message.split('\n')[0]}`);
+    }
+};
+/** `--pin newest`: the highest published version by semver — never a dist-tag, which can lag (`latest` sat on an
+ *  older alpha and `--pin latest` moved a product BACKWARDS, 2026-10-08). Canary and stage builds are not candidates. */
+export const NEWEST = 'newest';
+export function newestOf(versions) {
+    const parse = (v) => {
+        const m = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(v);
+        if (!m)
+            return null;
+        const pre = m[4]?.split('.') ?? [];
+        if (pre.some((x) => /canary|stage/i.test(x)))
+            return null;
+        return { nums: [Number(m[1]), Number(m[2]), Number(m[3])], pre };
+    };
+    const cmpPre = (a, b) => {
+        if (a.length === 0 && b.length === 0)
+            return 0;
+        if (a.length === 0)
+            return 1; // a release outranks any prerelease of the same triple
+        if (b.length === 0)
+            return -1;
+        for (let i = 0; i < Math.max(a.length, b.length); i++) {
+            const x = a[i];
+            const y = b[i];
+            if (x === undefined)
+                return -1;
+            if (y === undefined)
+                return 1;
+            const nx = /^\d+$/.test(x) ? Number(x) : null;
+            const ny = /^\d+$/.test(y) ? Number(y) : null;
+            if (nx !== null && ny !== null) {
+                if (nx !== ny)
+                    return nx - ny;
+                continue;
+            }
+            if (nx !== null)
+                return -1;
+            if (ny !== null)
+                return 1;
+            if (x !== y)
+                return x < y ? -1 : 1;
+        }
+        return 0;
+    };
+    let best = null;
+    for (const v of versions) {
+        const p = parse(v);
+        if (!p)
+            continue;
+        if (!best) {
+            best = { v, p };
+            continue;
+        }
+        let c = 0;
+        for (let i = 0; i < 3 && c === 0; i++)
+            c = p.nums[i] - best.p.nums[i];
+        if (c === 0)
+            c = cmpPre(p.pre, best.p.pre);
+        if (c > 0)
+            best = { v, p };
+    }
+    return best?.v ?? null;
+}
 export const npmDistTags = async (pkg) => {
     try {
         const out = execFileSync('npm', ['view', pkg, 'dist-tags', '--json'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
@@ -18,12 +90,16 @@ export const npmDistTags = async (pkg) => {
     }
 };
 const EXACT = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
+/** The change field for a root `pnpm.overrides` entry (a manifest field name, read and written in place). */
+export const OVERRIDES_FIELD = 'pnpm.overrides';
+const overridesOf = (json) => (json.pnpm?.overrides ?? {});
 export async function planUpgrade(opts) {
     const scope = opts.scope ?? '@agenticprimitives/';
     const target = opts.mode === 'canary' ? 'canary' : opts.pin ?? '';
     if (opts.mode === 'pin' && !target)
-        throw new DevkitError(ERROR_CODES.E_USAGE, '--pin needs a version or a dist-tag (latest | alpha | canary | 1.2.3)');
+        throw new DevkitError(ERROR_CODES.E_USAGE, '--pin needs a version, a dist-tag or newest (newest | latest | alpha | canary | 1.2.3)');
     const resolve = opts.resolveDistTags ?? npmDistTags;
+    const resolveVersions = opts.resolveVersions ?? npmVersions;
     const manifests = workspaceManifests(opts.root);
     const deps = new Set();
     for (const m of manifests)
@@ -36,6 +112,13 @@ export async function planUpgrade(opts) {
                 deps.add(dep);
             }
         }
+    // A root `pnpm.overrides` entry pins a package for EVERY workspace member — it is the one place a product keeps a
+    // cohort (verifiable-content-demo), and left alone it silently held service-host's a2a five alphas back on
+    // 2026-10-09. It is upgraded with the rest.
+    for (const m of manifests)
+        for (const dep of Object.keys(overridesOf(m.json)))
+            if (dep.startsWith(scope))
+                deps.add(dep);
     const resolved = {};
     const unresolved = [];
     const notes = [];
@@ -44,6 +127,23 @@ export async function planUpgrade(opts) {
             resolved[dep] = target;
             continue;
         }
+        if (opts.mode === 'pin' && target === NEWEST) {
+            let versions;
+            try {
+                versions = await resolveVersions(dep);
+            }
+            catch (e) {
+                unresolved.push(`${dep}: ${e.message}`);
+                continue;
+            }
+            const v = newestOf(versions);
+            if (!v) {
+                unresolved.push(`${dep}: no published release or prerelease version (${versions.length} version(s), canary/stage excluded)`);
+                continue;
+            }
+            resolved[dep] = v;
+            continue;
+        }
         let tags;
         try {
             tags = await resolve(dep);
@@ -69,6 +169,13 @@ export async function planUpgrade(opts) {
                 changes.push({ manifest: m.file, field, dep, from: spec, to });
             }
         }
+    for (const m of manifests)
+        for (const [dep, spec] of Object.entries(overridesOf(m.json))) {
+            const to = resolved[dep];
+            if (!to || spec === to)
+                continue;
+            changes.push({ manifest: m.file, field: OVERRIDES_FIELD, dep, from: spec, to });
+        }
     let coherent = true;
     if (opts.mode === 'canary') {
         const shas = new Set(Object.values(resolved).map((v) => /-canary-([0-9a-f]+)$/.exec(v)?.[1] ?? v));
@@ -88,7 +195,7 @@ export function applyUpgradePlan(root, plan, opts = {}) {
         const abs = join(root, file);
         const json = JSON.parse(readFileSync(abs, 'utf8'));
         for (const c of changes) {
-            const section = json[c.field];
+            const section = c.field === OVERRIDES_FIELD ? overridesOf(json) : json[c.field];
             if (section && section[c.dep] !== undefined)
                 section[c.dep] = c.to;
         }

package/dist/upgrade.js.map

@@ -1 +1 @@
-{"version":3,"file":"upgrade.js","sourceRoot":"","sources":["../src/upgrade.ts"],"names":[],"mappings":"AAAA,qHAAqH;AACrH,+GAA+G;AAC/G,iHAAiH;AACjH,kHAAkH;AAClH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAsB,MAAM,WAAW,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAwB,MAAM,gBAAgB,CAAC;AAoB1E,MAAM,CAAC,MAAM,WAAW,GAAoB,KAAK,EAAE,GAAG,EAAE,EAAE;IACxD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QAC/H,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAA2B,CAAC;IACnD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,WAAW,CAAC,WAAW,CAAC,SAAS,EAAE,YAAY,GAAG,sBAAuB,CAAW,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC3H,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,KAAK,GAAG,mCAAmC,CAAC;AAElD,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAA6I;IAC7K,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,qBAAqB,CAAC;IAClD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC;IAClE,IAAI,IAAI,CAAC,IAAI,KAAK,KAAK,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,WAAW,CAAC,WAAW,CAAC,OAAO,EAAE,uEAAuE,CAAC,CAAC;IACxJ,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,IAAI,WAAW,CAAC;IACpD,MAAM,SAAS,GAAG,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,SAAS;QAAE,KAAK,MAAM,KAAK,IAAI,CAAC,cAAc,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,sBAAsB,CAAU,EAAE,CAAC;YACxI,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;gBAC9D,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC;oBAAE,SAAS;gBACrC,IAAI,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,uBAAuB;oBAAE,SAAS;gBAC7E,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAChB,CAAC;QACH,CAAC;IACD,MAAM,QAAQ,GAA2B,EAAE,CAAC;IAC5C,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QACnC,IAAI,IAAI,CAAC,IAAI,KAAK,KAAK,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;YAAC,SAAS;QAAC,CAAC;QACpF,IAAI,IAA4B,CAAC;QACjC,IAAI,CAAC;YAAC,IAAI,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;QAAC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YAAC,UAAU,CAAC,IAAI,CAAC,GAAG,GAAG,KAAM,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;YAAC,SAAS;QAAC,CAAC;QAC9G,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;QACvB,IAAI,CAAC,CAAC,EAAE,CAAC;YAAC,UAAU,CAAC,IAAI,CAAC,GAAG,GAAG,SAAS,MAAM,mBAAmB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC;YAAC,SAAS;QAAC,CAAC;QACzH,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpB,CAAC;IACD,MAAM,OAAO,GAAoB,EAAE,CAAC;IACpC,KAAK,MAAM,CAAC,IAAI,SAAS;QAAE,KAAK,MAAM,KAAK,IAAI,CAAC,cAAc,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,sBAAsB,CAAU,EAAE,CAAC;YACxI,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;gBAC9D,MAAM,EAAE,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;gBACzB,IAAI,CAAC,EAAE,IAAI,IAAI,KAAK,EAAE;oBAAE,SAAS;gBACjC,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;YACjE,CAAC;QACH,CAAC;IACD,IAAI,QAAQ,GAAG,IAAI,CAAC;IACpB,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACnG,QAAQ,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;QAC1B,IAAI,CAAC,QAAQ;YAAE,KAAK,CAAC,IAAI,CAAC,4BAA4B,IAAI,CAAC,IAAI,0HAA0H,CAAC,CAAC;IAC7L,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AACrF,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,IAAiB,EAAE,OAAmC,EAAE;IACrG,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,MAAM,UAAU,GAAG,IAAI,GAAG,EAA2B,CAAC;IACtD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO;QAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACrG,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,UAAU,EAAE,CAAC;QACzC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAoB,CAAC;QACtE,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,CAAuC,CAAC;YACpE,IAAI,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,SAAS;gBAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QACrE,CAAC;QACD,aAAa,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QACzD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC;IACD,MAAM,IAAI,GAAkB,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IAC1F,IAAI,CAAC,QAAQ,GAAG,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;IACvD,IAAI,IAAI,CAAC,aAAa;QAAE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC;IACzD,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACtB,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IACjC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAiB;IACjD,MAAM,KAAK,GAAG,CAAC,gBAAgB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,eAAe,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,uBAAuB,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC3Q,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACtG,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,UAAU;QAAE,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,EAAE,CAAC,CAAC;IACnE,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACnD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}
+{"version":3,"file":"upgrade.js","sourceRoot":"","sources":["../src/upgrade.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "@agenticprimitives/devkit",
-  "version": "0.0.0-alpha.2",
+  "version": "0.0.0-alpha.21",
   "description": "The Developer Kit core (spec 398 §10 / spec 399 §3): `ap doctor` runs the doctrine gates as data + pure rules over any tree, `ap doctor --rules` projects one pinned rules source into AGENTS.md / CLAUDE.md / .cursor/rules by digest, `ap upgrade` rewrites every @agenticprimitives/* pin to one coherent exact set, and `ap conform` / `ap test` dispatch to the packages that own conformance and live gates.",
+  "homepage": "https://agenticprimitives.dev",
+  "bugs": {
+    "url": "https://github.com/agentictrustlabs/agenticprimitives/issues"
+  },
+  "author": {
+    "name": "Agentic Trust Labs",
+    "url": "https://agenticprimitives.dev"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -32,12 +40,15 @@
     "access": "public"
   },
   "dependencies": {
-    "@agenticprimitives/capability-claims": "0.0.0-alpha.20"
+    "@agenticprimitives/capability-claims": "0.0.0-alpha.33",
+    "@agenticprimitives/mcp-protocol": "0.0.0-alpha.4"
   },
   "peerDependencies": {
-    "@agenticprimitives/a2a": "0.0.0-alpha.20",
-    "@agenticprimitives/evaluation": "0.0.0-alpha.2",
-    "@agenticprimitives/mcp-protocol": "0.0.0-alpha.2"
+    "@agenticprimitives/a2a": "^0.0.0-alpha.35",
+    "@agenticprimitives/evaluation": "^0.0.0-alpha.6",
+    "@agenticprimitives/harness": "^0.0.0-alpha.16",
+    "@agenticprimitives/orchestration": "^0.0.0-alpha.14",
+    "@agenticprimitives/provenance-node": "^0.0.0-alpha.10"
   },
   "peerDependenciesMeta": {
     "@agenticprimitives/a2a": {
@@ -46,12 +57,19 @@
     "@agenticprimitives/evaluation": {
       "optional": true
     },
-    "@agenticprimitives/mcp-protocol": {
+    "@agenticprimitives/harness": {
+      "optional": true
+    },
+    "@agenticprimitives/orchestration": {
+      "optional": true
+    },
+    "@agenticprimitives/provenance-node": {
       "optional": true
     }
   },
   "devDependencies": {
-    "vitest": "^4.1.8"
+    "vitest": "^4.1.11",
+    "@agenticprimitives/harness": "0.0.0-alpha.16"
   },
   "keywords": [
     "agentic",
@@ -59,7 +77,12 @@
     "devkit",
     "doctor",
     "developer-kit",
-    "cli"
+    "cli",
+    "agentic-primitives",
+    "agenticprimitives",
+    "ai-agents",
+    "agent-authority",
+    "agentic-trust"
   ],
   "scripts": {
     "sync-rules": "node scripts/sync-rules.mjs",

package/rules/hard-rules.md

@@ -1,8 +1,8 @@
 # Hard rules (root CLAUDE.md)
 
 - **Smart Agent address is the canonical identifier.** Every person, org, service agent, and treasury IS its ERC-4337 SA address. Names, profiles, ERC-8004 entries, ANS handles, HCS topics — all facets pointing AT the canonical address. Cross-package APIs take `Address`, not names. See [ADR-0010](docs/architecture/decisions/0010-smart-agent-canonical-identifier.md) + [spec 220](specs/220-agent-identity-bootstrap.md) for the bootstrap process (deploy → forced-unique name → custody → optional facets).
-- **Every Smart Agent is a Person, an Organization, or a Service — nothing else.** PROV-O's trichotomy (`prov:Person`/`prov:Organization`/`prov:SoftwareAgent`), mirrored by `AgentType = 'person' | 'org' | 'service'` in `@agenticprimitives/types`. Treasury, indexer, relay, marketplace, data-source are **Service roles** (profile `serviceType` / app-level kinds), never new classes; UI groups by class and labels by role; app kinds map DOWN to a class, never up into the enum ([ADR-0046](docs/architecture/decisions/0046-agent-classification-person-org-service.md), specs 217/225 §6). **A demo person SA is never also their org SA** — do not reuse “his own SA” as the organization ([agent-rules/demo-person-org-distinct.md](docs/architecture/agent-rules/demo-person-org-distinct.md), `pnpm check:demo-person-org-distinct`).
-- **Canonical identity persists; credentials rotate.** Passkeys, SIWE EOAs, hardware wallets are control credential facets — replaceable, not the identity. Credential add / replace / remove is a custody-policy-governed operation (trustee quorum, guardian quorum, multi-credential self-recovery, or multi-sig), NEVER a delegation. The SA address NEVER changes during credential recovery. Delegations issued by the SA remain valid after rotation. See [ADR-0011](docs/architecture/decisions/0011-credential-recovery-and-re-association.md) + [spec 221](specs/221-credential-recovery.md).
+- **Every Smart Agent is a Person, an Organization, or a Service — nothing else.** PROV-O's trichotomy (`prov:Person`/`prov:Organization`/`prov:SoftwareAgent`), mirrored by `AgentType = 'person' | 'org' | 'service'` in `@agenticprimitives/types`. Treasury, indexer, relay, marketplace, data-source are **Service roles** (profile `serviceType` / app-level kinds), never new classes; UI groups by class and labels by role; app kinds map DOWN to a class, never up into the enum ([ADR-0046](docs/architecture/decisions/0046-agent-classification-person-org-service.md), specs 217/225 §6). **A demo person SA is never also their org SA** — do not reuse “his own SA” as the organization ([agent-rules/demo-person-org-distinct.md](docs/architecture/agent-rules/demo-person-org-distinct.md); enforced in the product repos by the `ap doctor` rule `demo-person-org-distinct`).
+- **Canonical identity persists; credentials rotate.** Passkeys, SIWE EOAs, hardware wallets are control credential facets — replaceable, not the identity. Credential add / replace / remove is a custody-policy-governed operation (trustee quorum, guardian quorum, multi-credential self-recovery, or multi-sig), NEVER a delegation. The SA address NEVER changes during credential recovery. **Every standing grant is re-approved by the ROTATION ceremony under the new custody epoch, and never by recovery** (spec 410 §1; the pre-epoch sentence "delegations remain valid after rotation" is retired): a rotation is `add → retire → approveDigest×N` in one transaction, a recovery is `add → retire → revokeAll` and the person re-issues from a reviewed list; only the account computes an approved-hash key (`approveDigest`), the registry is never an execute target. See [ADR-0011](docs/architecture/decisions/0011-credential-recovery-and-re-association.md) + [spec 221](specs/221-credential-recovery.md).
 - **Specs precede non-trivial code.** New `specs/2XX-*.md` before architecture changes; the spec is the architect-of-record.
 - **Always check smart-agent first.** Before designing any non-trivial capability look at the analog in `/home/barb/smart-agent`. New specs MUST include a "Reference: smart-agent patterns to port" section. Deliberate divergence must say why.
 - **Package boundaries** are one-directional: `types ← identity-auth ← agent-account ← delegation ← mcp-runtime`, plus `key-custody → delegation`, `tool-policy → mcp-runtime`, and the custody-layer fork `types ← custody` (depended on by `agent-account` and `delegation`; see [spec 213](specs/213-custody-layer-carve-out.md) for the firewall). No back-edges. `tool-policy` and `types` are transport-agnostic (no MCP/A2A/LangChain/Vercel imports).
@@ -41,7 +41,7 @@
 - **Per-package context budget:** `CLAUDE.md` ≤ 60 lines, `AUDIT.md` ≤ 150 lines, `README.md` ≤ 1800 words. If you're tempted to bloat one, fix the package shape.
 - **No `eth_getLogs` in product read paths.** Package and app hot paths use `readContract` only; chain history and human-readable reverse strings come from on-chain storage, an explicit indexer, or app cache — never inline log scans ([ADR-0012](docs/architecture/decisions/0012-no-eth-getlogs-in-product-read-paths.md)). No exceptions: the last walker (`agent-naming` `reverseResolve` log fallback) was removed once spec/222 `reverseResolveString` landed.
 - **No silent fallbacks.** A read/auth path has exactly ONE mechanism. If the canonical path has no answer it returns `null`/empty or throws — it does NOT escalate to a second, different, more expensive mechanism (`try fast catch slow`, empty-result → log walk, strong-check → weak-check). Empty is an answer, not a trigger. Bounded retries of the *same* call and cache-first reads (cache holds the canonical answer) are fine; switching mechanism is not ([ADR-0013](docs/architecture/decisions/0013-no-silent-fallbacks.md)).
-- **The discovery knowledge base holds ONLY public, on-chain-derivable data.** The GraphDB A-box (projected by `demo-discovery-indexer`, read by `demo-discovery-mcp`/`-a2a`) is a world-readable read tier — populate it ONLY with facts any party could reproduce from on-chain state, transactions, or event logs (naming, registry entries, profile, relationships, attestations, custodian/passkey membership from `CustodianAdded`/`PasskeyAdded` logs). NEVER per-viewer state, session/credential secrets, off-chain/relying-app-local data, vault contents, PII, or private linkage ([ADR-0025](docs/architecture/decisions/0025-related-agents-are-private-vault-credentials.md)) — not even hashed, not even temporarily, not even to make a check faster. No secret-derived rows: any opaque form (e.g. custody membership as `sha256(credential‖smartAgent)`) MUST be a public, unsalted, on-chain-*reproducible* function — no server pepper. The indexer is the only writer; consumer services MUST NOT write viewer-/request-derived facts back. The claim: reading the whole KB reveals nothing reading the chain wouldn't ([ADR-0040](docs/architecture/decisions/0040-knowledge-base-only-public-onchain-data.md)).
+- **The discovery knowledge base holds ONLY public, on-chain-derivable data.** The GraphDB A-box (projected by `demo-discovery-indexer`, read by `demo-discovery-mcp`/`-a2a`) is a world-readable read tier — populate it ONLY with facts any party could reproduce from on-chain state, transactions, or event logs (naming, registry entries, profile, relationships, attestations, custodian/passkey membership from `CustodianAdded`/`PasskeyAdded` logs). NEVER per-viewer state, session/credential secrets, off-chain/relying-app-local data, vault contents, PII, or private linkage ([ADR-0025](docs/architecture/decisions/0025-related-agents-are-private-vault-credentials.md)) — not even hashed, not even temporarily, not even to make a check faster. No secret-derived rows: any opaque form (e.g. custody membership as `sha256(credential‖smartAgent)`) MUST be a public, unsalted, on-chain-*reproducible* function — no server pepper. The indexer is the only writer; consumer services MUST NOT write viewer-/request-derived facts back. The claim: reading the whole KB reveals nothing reading the chain wouldn't ([ADR-0040](docs/architecture/decisions/0040-knowledge-base-only-public-onchain-data.md)). Amended carve-outs, each opt-in, signed or verified, and read the way a stranger would read it: A2A cards (286), signed Home manifests (323), and **public + owner-released shelf works** with their retrieval index (413; the index is never bound beside a vault, `check:no-vector-over-vault`).
 - **On the A2A→MCP hop, Web3 is the authority; MCP OAuth is only the ingress envelope.** When an A2A service agent calls an MCP service, the authorization decision is ALWAYS the Web3 chain — on-chain delegation + signature validation (ERC-1271/6492/ECDSA/WebAuthn via `UniversalSignatureValidator`) + entitlement + tool policy (+ key-release grant + audit for data) — re-run server-side against the principal SA. We ship MCP's OAuth (RFC 9728 bearer / protected-resource metadata) as a generic ingress *adapter* so external MCP clients interoperate, but the bearer is at most a transport envelope: it carries only `ap_principal` + a `ap_grant_ref`/`ap_grant_hash` to an encrypted grant bundle, NEVER delegation/entitlement payload or field-level authority. Do NOT let OAuth drift inward: field/record access is never encoded in scopes (`vault:read` ≠ "decrypt all PII"), OAuth claims (`scope`/`aud`/`client_id`) are never trusted *as* the grant, an inbound MCP token is never reused for the next hop (fresh token / RFC 8693 exchange), and the Web3 gates are never skipped because "OAuth already authenticated the caller." For internal A2A→MCP hops the public OAuth ingress may be absent/skipped (the A2A bridge handles MCP tokens server-side, never exposing them downstream) — the delegation+signature+entitlement+policy gates are not. One mechanism (ADR-0013): OAuth-fail rejects, it does not fall back to a weaker token-trust path. When the standard and the substrate conflict, the substrate wins. ERC-4337 SA-bound, signature-verified, on-chain-revocable delegation is our differentiator from OAuth — never trade it for an opaque issuer-granted scope ([ADR-0041](docs/architecture/decisions/0041-web3-authority-not-oauth-on-a2a-to-mcp.md) + [spec 277](specs/277-mcp-delegated-vault-authorization.md) + [spec 269](specs/269-async-delegation-authorized-a2a.md) + [spec 270](specs/270-del-001-activation.md)).
 - **Agentic architecture: first-party web expresses INTENTS to an A2A agent; it NEVER drives MCP directly.** A2A is the orchestration / intelligence / discovery layer — it discovers which capability satisfies a declarative goal, plans (planner/LLM/LangChain), assembles authority (delegation/entitlement), and composes MCP tools AS PRIMITIVES. A first-party UI (demo-web-pro, demo-sso-next) says "rebalance the treasury" / "read Alice's PII for purpose X" — a goal, not a tool name, payload, or call sequence — and posts it to an a2a agent. **`web → (edge) → MCP /tools|/mcp|/mcp/native` directly is the anti-pattern (RPC with extra steps) for first-party apps.** The public MCP ingress (`/mcp`, `/mcp/native`) is interop for EXTERNAL agents/clients only; the Act6 OAuth/Native panels are external-MCP-client *demonstrations of a primitive*, NOT a product-UX model (keep them labelled as such). **Orchestration is a Ring-0 primitive, not external** — the agentic loop (intent→plan→compose→observe→re-plan), the planner/reasoner PORT, and the tool/skill model live in a pure `packages/*` orchestration core; ONLY the concrete LLM-framework binding (LangChain/OpenAI/Anthropic SDK) lives in a dedicated in-repo adapter behind the port — the `chain-state` + `chain-state-viem` pattern (ADR-0037 exiles protocol-conformance + deployed-infra, NOT libraries). `service-agent` stays the deterministic compile/run target; the Ring-0 orchestration core PRODUCES its plans. Apps wire model creds/config; they don't re-implement the loop. The edge is orthogonal: it admits, it does not orchestrate (ADR-0043). Honest tension: the first-party web↔a2a surface is RPC-shaped TODAY (`/session/*`, `/account/*`, `/mcp/person/pii` — verbs); the intent layer (A2A messages/tasks against `A2aTaskDO` + `service-agent` plans) is the objective — build NEW first-party surfaces intent-first; the relayer verbs are legacy. Enforced by review + `check:no-direct-mcp-in-web` (browser-app source; allowlist the labelled external-client demo panels) ([ADR-0044](docs/architecture/decisions/0044-a2a-is-the-agentic-orchestration-layer.md) + [docs/architecture/principles.md](docs/architecture/principles.md)).
 - **Packages are GENERIC trust building blocks; white-label / vertical / deployment code lives in apps.** `packages/*` are reusable + vertical-agnostic. They MUST NOT contain (a) **branding / vertical content** — faith vocabulary (ministry, congregation, discipleship, parish, denomination, gospel, scripture — **`church`/`circle` are the one carve-out: Ring-0 derived AGENT TYPES since 2026-08-30, ADR-0061 amendment; the KIND is generic, the content is not**), white-label/product names, marketing copy, themes; (b) **vertical-specific flows** — faith onboarding steps, impact-portal features; (c) **deployment specifics** — concrete hostnames (`impact-agent.me`/`.io`), the `demo.agent` subregistry, hosting providers (`*.pages.dev`/`*.workers.dev`/`vercel`), host/subdomain parsing. All of that is the **app** layer's job, supplied as an **app-level white-label config object** (spec 234) the generic core consumes. The `.agent` TLD itself is the naming protocol (owned by `agent-naming`) and is allowed. Enforced by `pnpm check:no-domain-in-packages` (hostnames + `demo.agent` + faith vocab) + `check:forbidden-terms`; the rest is doctrine ([ADR-0021](docs/architecture/decisions/0021-generic-packages-vs-white-label-apps.md)). Each app centralizes its domain/white-label literals in one module (e.g. `src/lib/domain.ts`), never scattered.

package/rules/service-agent-birthrights.md

@@ -0,0 +1,76 @@
+# A service agent is born with its storage, its door, its playbook and its harness
+
+**Applies to every path that creates a Service Agent** (`.svc`, `.treasury`, `.workspace`, `.registry`, and any
+`prov:SoftwareAgent`): the Home's "Add an agent" ceremony, `createAgentWithBirthrights`, the KMS bootstrap, the
+runtime's `child-agent.create` step, and **every charter script** in a product or demo repository
+(`charter-services.mjs`, `mint-workspace-persona.mjs`, `provision-naming-service.mts`, the next one).
+
+## One sentence
+
+**Chartering a service agent is not finished when the account is deployed and named.** It is finished when the
+agent can be asked, can record what it did, and its Home can show it — the same four birthrights every person,
+organization and treasury already receive at creation, applied to services with no exception for "it is only a script".
+
+## Why this keeps getting re-derived
+
+A service "works" the moment its endpoint answers. Nobody notices that nothing lands until its steward opens
+Activities and reads **"No runs yet"** — after a hundred asks. It happened to `ligonier.svc` (spec 386/387: stewardship
+and the vault-key ceremony had to be run by hand before `assign-org-archetype` would even work) and again to
+`scripture-resolver.svc` on 2026-10-08 (chartered 2026-09-21 under `ruth.me`; no vault key, a pre-widening grant, no
+playbook, its own ask loop outside the harness; Ruth's Home empty). The Home's own ceremony has the same hole: in
+`createAgentWithBirthrights` the storage enable runs only for `kind === 'org'`, the content-read grant only for a
+team, and the default-playbook map has no entry for a service.
+
+Every one of those is a working system honestly enforcing a birthright nobody gave.
+
+## The birthrights — all four, at charter, whoever charters
+
+| # | Birthright | What it is | Without it |
+| --- | --- | --- | --- |
+| 1 | **Identity + standing** | the account deployed; its typed name bought or claimed; its public records written (`atl:agentType`, `a2aEndpoint`, `atl:cardUri`, `atl:mcpEndpoint` when it serves one, `siteUrl` when it has a site); the **stewardship link** from the service to its steward recorded in the steward's vault | nobody can reach it by name; its steward's Home does not list it; "only the agent's custodian…" |
+| 2 | **Storage** | the **vault key binding** (spec 278: provision + bind, signed by the custodian, ERC-1271 against the service's account) and the **standing interactions grant** to its own door (spec 322 plane B, the scope list the Home builds today) | `vault_key_unauthorized` on every read; `record_scope_denied` on every write; nothing it does can be recorded |
+| 3 | **Playbook** | the archetype assignment in its vault, by definition digest (spec 354 §4.3): the default for its kind, or the one its charter names (`content-catalog` for a catalog, `treasury-steward` for a treasury, the app's own for an app) | the bare harness — a service that moves value and tells nobody (spec 360's incident) |
+| 4 | **Harness** | the agent runs **the** harness, not a loop of its own: hosted by the runtime (records name its MCP; nothing to deploy) or self-hosted with the Service Host embedded (spec 433) — either way runs, receipts and `run.provenance:<runRef>` land in **its** DO and **its** vault. **A self-hosted agent also issues its READ WIRE to its steward's Home** (spec 433 W2): a delegation from the agent to the Home runtime's interactions-session key, pinned `harness.read` only, signed by the custodian the way its storage grant is (`issue-self-host-read-wire.mts`) — the Home cannot verify its own session at another host, so the steward's Activities page reads the agent's runs under the agent's own wire, or not at all | an endpoint that answers and an estate that never saw it; runs kept at a host the steward's Home is refused at ("this host admits no Home session") |
+
+A charter that cannot complete a birthright **says so and stops**, the way the Home's org-create says "storage
+not enabled — Enable (steward)". It does not deploy, name and walk away. A script that mints a key, deploys and
+prints "next, at the Home: …" has handed the operator a list it should have run.
+
+## The pattern (for a script or a ceremony)
+
+```
+deploy → name + records → stewardship link
+      → vault-key bind (278)  → interactions grant (322 §2 B, current scopes)
+      → archetype assignment (354 §4.3, by digest)
+      → the harness: records name the MCP (hosted) │ the app embeds the Service Host (433)
+                                                    │   + the read wire to the steward's Home (433 W2: issue-self-host-read-wire.mts)
+      → verify: /harness/ask on the new agent answers; its steward's Home lists it with 0 runs, not "not enabled"
+```
+
+Each leg is idempotent and re-runnable (`is-bound`, the grant's `current`, the assignment's digest); a repair is
+the same script run again. The recovery scripts that exist today — `bind-vault-key.mts`, `reissue-service-grant.mts`,
+`record-service-stewardship.mts`, `assign-org-archetype.mts` — are the legs of this one ceremony, and a charter
+script calls them (or their library form) rather than leaving them for later.
+
+## What this rule does NOT say
+
+- It does not make a service a person. Storage for a service holds **its** records (its runs, its catalog, its
+  receipts) and never a client's (the runtime refuses a service that files a client's study records in its own
+  cabinet). A client's data lives in the client's vault, under the client's grant.
+- It does not grant authority. Every birthright is a precondition of being *accountable*; none of them lets the
+  agent do anything a mandate would not. A service with all four still parks on a step that needs its steward's
+  signature.
+- It does not pick the hosting shape. Hosted (default; no app) or self-hosted (an app with the Service Host) are
+  both allowed; a self-hosted service that runs its own loop outside the harness is not.
+
+## Enforcement
+
+- Product repos: `ap doctor` rule `service-birthrights` (spec 433 W3) — a charter path that deploys a service kind
+  without calling every leg, or a `.svc` app that mounts an A2A surface without the Service Host, is a finding.
+- The runtime: a service with no vault key binding cannot start a run (`vault_key_unauthorized`, fail closed —
+  already true); the Service Host refuses to start for the same reason.
+- The Home (spec 433 W3): `createAgentWithBirthrights` runs legs 2 and 3 for `kind === 'service'` and every service
+  kind, not only `org`; the default-playbook map gains the service kinds.
+
+Related: spec 433 · spec 354 §3 (born with a playbook) · spec 321/322 (storage at create) · spec 278 (vault key) ·
+spec 346 (typed names + `atl:agentType`) · ADR-0055 (the vault is the record) · [`demo-person-org-distinct.md`](./demo-person-org-distinct.md).

package/rules/vault-is-the-record-apps-hold-references.md

@@ -0,0 +1,47 @@
+# The vault is the record; an app holds references, never copies
+
+**Binding rule for every product app on the substrate (Source Publishing, Field, Skills, Gather, the Home's own
+serving planes) and for the A2A runtime.** Canonical copy; Cursor has no `.mdc` for it yet.
+
+## The rule
+
+1. **A person's data lives in their vault, behind MCP, under their own key.** Name, email, phone, location, the
+   publisher card, a work's text, a profile of any kind — one record, in the owner's vault, reachable only through a
+   delegation the owner signed. Nothing about a person is authoritative anywhere else.
+2. **An app keeps REFERENCE facts and its own operational records — nothing that is the person's.** Reference: the Smart
+   Agent address, the handle the app assigned, the client's own wire (ask-as-me) and grants, ids of records it wrote
+   through the owner's agent. Operational: what the app itself produced and must serve (a public replica of a SIGNED,
+   PUBLIC artifact; an archive the product exists to keep; verification results). Never a copy of a private field
+   because it was convenient to have beside the id.
+3. **A copy that exists for speed is a cache with a source, never a second record.** The Home's KV Library cache is
+   rebuildable from the vault and says `source: cache` on the wire; the runtime's DO storage is a serving plane
+   (ADR-0055). If wiping it is a bereavement and not a rebuild, it belonged in the vault.
+4. **Reads are fast by GRANT, not by copying.** An app that needs a person's record at request latency holds a scoped,
+   revocable **read grant** the person signed at connect (registry `read_grant.resources`; spec 341 §4.3b) and reads
+   it in one call under its own bearer — no harness, no model. What is public is read through the owner's agent's
+   public lane (spec 412) — no credential at all. The one thing an app never does is answer speed by storing.
+5. **Writes go through the owner's agent, as the owner.** An app never writes a vault. It asks the person's agent
+   (`ask-as-me` → `harness.ask` → a self-acting capability such as `profile.contact.update`, `library.file.save`), and
+   the agent writes as the person, into the person's vault, leaving a run of theirs. A form in an app that collects a
+   person's name is a form that writes it to their Home — the app forgets it the moment the write lands.
+6. **The A2A runtime is the same.** It reads and writes the owner's records under the owner's grants; it holds serving
+   state, receipts, cursors and caches, never the person's data as its own.
+
+## Why
+
+Every copy is a second enforcement point with a second authority model, and a record nobody can carry to another Home.
+The publishing app kept a directory row with the person's name, organization, byline and topics beside their address,
+and a profile document with their email — three copies of things the Home knew, each drifting the day the Home changed
+(2026-09-21). The doctrine that made revocation real (per-app grants, ADR-0041) is undone by a copy that survives the
+revoke.
+
+## How to apply
+
+- Designing a table: for each column ask *whose fact is this?* A person's → not here; read it under a grant or through
+  the public lane. The app's own → fine.
+- Designing a form: if it collects a person's fact, its submit is a write to their Home through their agent, and the
+  page re-reads it from there.
+- Reviewing an app: `grep` its schema and browser storage for names, emails, phones, addresses, profile text. Each hit
+  is a finding unless it is inside a signed public artifact the app exists to serve.
+- Performance complaint about a person's data: the answer is a read grant (private) or the public lane (public),
+  declared in the registry — never a local copy.