yay-layer 1.0.0-rc.1

package/src/gate.js

@@ -0,0 +1,252 @@
+'use strict';
+// `yay gate` — bootstrap the enforcement gate for a project on ANY git host:
+//   • write the CI pipeline that runs `yay verify --strict` on PRs/MRs,
+//   • optionally install a local pre-push hook for solo/offline feedback,
+//   • print the branch-protection steps (which live in the host's settings and
+//     can't be scripted with a normal token).
+// The gate itself is platform-agnostic — the ONLY host-specific part is the pipeline
+// file's syntax and where branch protection lives. `--for <platform>` picks that.
+// String generators are pure (easy to test); file writes are separate.
+
+const fs = require('fs');
+const path = require('path');
+
+const WORKFLOW_REL = '.github/workflows/yaylayer.yml'; // default (github), kept for back-compat
+const NPM_NOTE = "# Until yay-layer is published to npm, change the install line to:  npm install -g github:jonas-developer/yay-layer";
+const args = ({ scope = '', root = '' }) => (scope ? ` --dir ${scope}` : '') + (root ? ` --root ${root}` : '');
+
+// ── per-platform CI pipeline generators (all just: install node → install yay → verify --strict) ──
+function githubWorkflow(o = {}) {
+  return `# Generated by \`yay gate\`. The real gate is this check PLUS a branch-protection rule on
+# main that REQUIRES the "gate" check (see the printed steps).
+${NPM_NOTE}
+name: YayLayer
+on:
+  pull_request:
+  push:
+    branches: [main]
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: Install YayLayer
+        run: npm install -g ${o.pkg || 'yay-layer'}
+      - name: Verify the gate
+        run: yay verify --strict${args(o)}
+`;
+}
+function azureWorkflow(o = {}) {
+  return `# Generated by \`yay gate --for azure\`. The real gate is this pipeline PLUS a Branch Policy
+# on main that REQUIRES it (Repos → Branches → main → Branch policies → Build Validation).
+${NPM_NOTE}
+trigger:
+  branches: { include: [main] }
+pr:
+  branches: { include: [main] }
+pool:
+  vmImage: ubuntu-latest
+steps:
+  - task: NodeTool@0
+    inputs:
+      versionSpec: '20.x'
+  - script: npm install -g ${o.pkg || 'yay-layer'}
+    displayName: Install YayLayer
+  - script: yay verify --strict${args(o)}
+    displayName: YayLayer gate
+`;
+}
+function gitlabWorkflow(o = {}) {
+  return `# Generated by \`yay gate --for gitlab\`. The real gate is this job PLUS a Protected branch on
+# main with "Pipelines must succeed" + merge-request approvals (Settings → Repository / Merge requests).
+${NPM_NOTE}
+stages: [verify]
+yaylayer-gate:
+  stage: verify
+  image: node:20
+  script:
+    - npm install -g ${o.pkg || 'yay-layer'}
+    - yay verify --strict${args(o)}
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_BRANCH == "main"'
+`;
+}
+function bitbucketWorkflow(o = {}) {
+  const step = `      - step:\n          name: YayLayer gate\n          script:\n            - npm install -g ${o.pkg || 'yay-layer'}\n            - yay verify --strict${args(o)}`;
+  return `# Generated by \`yay gate --for bitbucket\`. The real gate is this pipeline PLUS a Branch
+# restriction on main requiring a passing build + a PR (Repository settings → Branch restrictions).
+${NPM_NOTE}
+image: node:20
+pipelines:
+  pull-requests:
+    '**':
+${step}
+  branches:
+    main:
+${step}
+`;
+}
+
+// Gerrit has no native in-repo pipeline: it gates via the "Verified" label + a submit requirement,
+// and delegates the actual run to Zuul (its native check/gate CI) or Jenkins. We emit a Zuul config
+// (+ its companion playbook, since a Zuul job runs a playbook, not an inline command).
+function gerritZuul(o = {}) {
+  return `# Generated by \`yay gate --for gerrit\`. Gerrit gates via the "Verified" LABEL, not a required
+# "check": your CI runs on refs/for/* and votes Verified +1/-1, and you make Verified+1 a SUBMIT
+# REQUIREMENT so nothing merges until the gate is green (see the printed steps). This is a Zuul config
+# (Gerrit's native check/gate CI) — it runs playbooks/yaylayer-gate.yaml. Using Jenkins instead? Run
+# the same \`yay verify --strict\` in your job via the Gerrit Trigger plugin; the contract is identical.
+${NPM_NOTE}
+- job:
+    name: yaylayer-gate
+    description: YayLayer verifier gate (fails on Red / Unsigned / Pink).
+    run: playbooks/yaylayer-gate.yaml
+    nodeset:
+      nodes:
+        - name: ubuntu
+          label: ubuntu-jammy   # depends on your Zuul deployment — change to a label it provides
+- project:
+    check:
+      jobs: [yaylayer-gate]
+    gate:
+      jobs: [yaylayer-gate]
+`;
+}
+function gerritPlaybook(o = {}) {
+  return `# Generated by \`yay gate --for gerrit\` (companion to .zuul.yaml — the job's playbook).
+- hosts: all
+  tasks:
+    - name: Install YayLayer
+      shell: npm install -g ${o.pkg || 'yay-layer'}
+    - name: Verify the gate
+      shell: yay verify --strict${args(o)}
+`;
+}
+
+// gitea/forgejo run GitHub-Actions-compatible workflows — same content, different path.
+const PLATFORMS = {
+  github: { rel: '.github/workflows/yaylayer.yml', workflow: githubWorkflow },
+  gitea: { rel: '.gitea/workflows/yaylayer.yml', workflow: githubWorkflow },
+  azure: { rel: 'azure-pipelines.yml', workflow: azureWorkflow },
+  gitlab: { rel: '.gitlab-ci.yml', workflow: gitlabWorkflow },
+  bitbucket: { rel: 'bitbucket-pipelines.yml', workflow: bitbucketWorkflow },
+  gerrit: { rel: '.zuul.yaml', workflow: gerritZuul, extra: [{ rel: 'playbooks/yaylayer-gate.yaml', gen: gerritPlaybook }] },
+};
+const PLATFORM_KEYS = Object.keys(PLATFORMS);
+const normPlatform = (p) => { const k = String(p || 'github').toLowerCase().replace('devops', '').replace('forgejo', 'gitea').trim(); return PLATFORMS[k] ? k : (k === 'ado' ? 'azure' : 'github'); };
+
+// Back-compat: the bare github generator.
+function ciWorkflow(o = {}) { return (PLATFORMS[normPlatform(o.platform)] || PLATFORMS.github).workflow(o); }
+
+function prePushHook({ scope = '' } = {}) {
+  const scopeArg = scope ? ` --dir ${scope}` : '';
+  return `#!/bin/sh
+# YayLayer local gate — refuses a push while any Cell is Red / Unsigned / Pink.
+# This is fast local feedback, NOT the real guarantee (bypass with: git push --no-verify).
+# The real gate is the CI check + branch protection on main.
+command -v yay >/dev/null 2>&1 || { echo "yaylayer: 'yay' not on PATH — skipping local gate"; exit 0; }
+yay verify --strict${scopeArg} || {
+  echo ""
+  echo "  push blocked by YayLayer — resolve Red/Unsigned/Pink (yay verify --problems), or: git push --no-verify"
+  exit 1
+}
+`;
+}
+
+function branchProtectionSteps(platform) {
+  const p = normPlatform(platform);
+  const common = 'Now nothing merges to main until the gate is green (no Red / Unsigned / Pink; Yellow is allowed).\nBranch protection lives in your host\'s settings only you control — a token cannot set it.';
+  if (p === 'azure') return [
+    'To make it enforce, add a Branch Policy on main (one-time, in Azure DevOps):',
+    '',
+    '  1. Commit azure-pipelines.yml, then Pipelines → New pipeline → point it at this repo/file and run it once.',
+    '  2. Repos → Branches → hover main → ⋯ → Branch policies.',
+    '  3. Build Validation → + → pick this pipeline; Trigger: Automatic; Policy requirement: Required.',
+    '  4. Also enable "Require a minimum number of reviewers" (≥1) so changes go through a PR.',
+    '', common,
+  ].join('\n');
+  if (p === 'gitlab') return [
+    'To make it enforce (one-time, in GitLab):',
+    '',
+    '  1. Commit .gitlab-ci.yml and let a pipeline run once.',
+    '  2. Settings → Repository → Protected branches → protect main (Allowed to merge: Maintainers).',
+    '  3. Settings → Merge requests → tick "Pipelines must succeed"; set required approvals ≥ 1.',
+    '', common,
+  ].join('\n');
+  if (p === 'bitbucket') return [
+    'To make it enforce (one-time, in Bitbucket):',
+    '',
+    '  1. Commit bitbucket-pipelines.yml (enable Pipelines in Repository settings) and let it run once.',
+    '  2. Repository settings → Branch restrictions → add a restriction on main.',
+    '  3. Require: a pull request, a minimum number of approvals (≥1), and "successful builds" before merging.',
+    '', common,
+  ].join('\n');
+  if (p === 'gerrit') return [
+    'Gerrit gates via the Verified LABEL (not a required "check") — one-time setup:',
+    '',
+    '  1. Commit .zuul.yaml + playbooks/yaylayer-gate.yaml so your CI runs `yay verify --strict`',
+    '     on every change (refs/for/*) — Zuul, or Jenkins via the Gerrit Trigger plugin.',
+    '  2. Make sure the CI account votes the Verified label from the result (+1 pass, -1 fail).',
+    '  3. Add a SUBMIT REQUIREMENT on the project: require Verified=MAX (and Code-Review=+2) to submit',
+    '     (Browse → Repositories → your repo → Submit requirements, or project.config).',
+    '  4. Block direct pushes to refs/heads/main so every change goes through review (refs/for/main).',
+    '', common,
+  ].join('\n');
+  if (p === 'gitea') return [
+    'To make it enforce (one-time, in Gitea/Forgejo):',
+    '',
+    '  1. Commit .gitea/workflows/yaylayer.yml (enable Actions for the repo) and let it run once.',
+    '  2. Settings → Branches → Branch protection → add a rule for main.',
+    '  3. Enable "Require status checks" → add the "gate" check; require a PR + approvals.',
+    '', common,
+  ].join('\n');
+  // github (default)
+  return [
+    'To make it enforce, require the check on main (one-time, in the browser):',
+    '',
+    '  1. Push this workflow to main FIRST (while main is still unprotected), and let',
+    '     it run once — the "gate" check only becomes selectable after it has run.',
+    '  2. GitHub → your repo → Settings → Rules → Rulesets → New ruleset → New branch ruleset.',
+    '  3. Name it (e.g. "main gate"); Enforcement: Active.',
+    '  4. Target branches → Add target → Include default branch (main).',
+    '  5. Tick: Require a pull request before merging.',
+    '  6. Tick: Require status checks to pass → search & select  gate  .',
+    '  7. Tick: Block force pushes.  Then Create.',
+    '', common,
+  ].join('\n');
+}
+
+// Write the pipeline file(s) for the chosen platform. Idempotent: skips an existing file unless force.
+// Some platforms (gerrit) need a companion file (a Zuul playbook) — those come back in `extra`.
+function writeWorkflow(root, opts = {}) {
+  const plat = PLATFORMS[normPlatform(opts.platform)] || PLATFORMS.github;
+  const writeOne = (rel, gen) => {
+    const abs = path.join(root, rel);
+    const existed = fs.existsSync(abs);
+    if (existed && !opts.force) return { action: 'skipped', path: rel };
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, gen(opts));
+    return { action: existed ? 'overwritten' : 'created', path: rel };
+  };
+  const main = writeOne(plat.rel, plat.workflow);
+  const extra = (plat.extra || []).map((ex) => writeOne(ex.rel, ex.gen));
+  return { action: main.action, path: main.path, extra };
+}
+
+// Install the pre-push hook. Idempotent unless force; needs a git repo.
+function writeHook(root, opts = {}) {
+  const dir = path.join(root, '.git', 'hooks');
+  if (!fs.existsSync(path.join(root, '.git'))) return { action: 'no-git', path: '.git/hooks/pre-push' };
+  const abs = path.join(dir, 'pre-push');
+  if (fs.existsSync(abs) && !opts.force) return { action: 'skipped', path: '.git/hooks/pre-push' };
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(abs, prePushHook(opts));
+  try { fs.chmodSync(abs, 0o755); } catch (_) {}
+  return { action: 'created', path: '.git/hooks/pre-push' };
+}
+
+module.exports = { ciWorkflow, prePushHook, branchProtectionSteps, writeWorkflow, writeHook, WORKFLOW_REL, PLATFORMS, PLATFORM_KEYS, normPlatform };

package/src/grants.js

@@ -0,0 +1,249 @@
+'use strict';
+// Autopilot — scoped, owner-signed delegation GRANTS, expanded in P3 into signed CAPABILITY
+// ENVELOPES with attenuating CHILD GRANTS.
+//
+// A grant lets the machine AUTO-APPROVE in-scope, non-sensitive Cells for a bounded window
+// (time + count + path/cell/risk envelope) without contacting the phone. It binds a machine-held
+// grant PUBLIC key (the laptop keeps the matching private key and signs auto-approvals with it).
+// The owner signs the grant on their phone (or local key) — the AI can never issue one. `yay verify`
+// accepts an auto-approval only when a valid, unexpired, unrevoked, in-count, in-envelope grant
+// covers it; the Cell is then GREEN-on-verify but marked AUTO on the TRUST axis and queued for
+// human ratification.
+//
+// ENVELOPE (P3): { allow:[globs], deny:[globs], cells:[ids], maxCells, maxRisk, deps, deployment,
+//                  childGrants:{allowed,maxDepth} }. Scope constraints (allow/deny/cells/maxCells/
+//                  maxRisk) are enforced NOW — we know where a change lands. Content constraints
+//                  (deps/deployment/network) are DETECTOR-GATED (D15): recorded + shown, enforced
+//                  only where a detector exists, so we never promise a boundary we can't verify.
+//
+// CHILD GRANTS (P3): a grant may carry `parent` + be signed by the parent's GRANT key (not an
+// owner). It can only ATTENUATE — allow ⊆ parent.allow, deny ⊇ parent.deny, maxCount ≤ parent
+// remaining, expiry ≤ parent, risk ≤ parent, depth ≤ parent.childGrants.maxDepth. The verifier
+// REFUSES any child that exceeds its parent, so no new authority is ever minted below the human
+// root. Off by default (parent must set childGrants.allowed).
+//
+// A grant/revoke is a signed event (same body-canonicalisation as roster.eventBytes), stored
+// append-only in .yaylayer/grants.json.
+const C = require('./crypto');
+const roster = require('./roster');
+const { nonDelegable, globToRe, cellTags } = require('./policy');
+
+function safeVerify(msg, sig, pub) { try { return !!(sig && pub && C.verify(msg, sig, pub)); } catch (_) { return false; } }
+
+const RISK = { low: 1, medium: 2, high: 3 };
+function riskRank(r) { return RISK[String(r || 'medium').toLowerCase()] || RISK.medium; }
+
+// Normalize a grant event's envelope, tolerating the legacy shape (`scope.cells` + `maxCount`).
+function envelopeOf(grant) {
+  const g = grant || {};
+  const env = g.envelope || {};
+  const legacyCells = (g.scope && Array.isArray(g.scope.cells)) ? g.scope.cells : null;
+  const cg = env.childGrants || {};
+  return {
+    allow: Array.isArray(env.allow) ? env.allow : [],
+    deny: Array.isArray(env.deny) ? env.deny : [],
+    allowTags: Array.isArray(env.allowTags) ? env.allowTags.map((t) => String(t).toLowerCase()) : [],
+    denyTags: Array.isArray(env.denyTags) ? env.denyTags.map((t) => String(t).toLowerCase()) : [],
+    guard: env.guard !== false, // default security guard ON unless explicitly lifted
+    cells: Array.isArray(env.cells) ? env.cells : (legacyCells || []),
+    maxRisk: env.maxRisk || null,
+    deps: env.deps || null,             // detector-gated (recorded)
+    deployment: env.deployment || null, // detector-gated (recorded)
+    childGrants: { allowed: !!cg.allowed, maxDepth: cg.maxDepth != null ? cg.maxDepth : (cg.allowed ? 1 : 0) },
+  };
+}
+
+function pathMatchesAny(globs, file) {
+  if (!globs || !globs.length) return null; // no constraint
+  return globs.some((g) => { try { return globToRe(g).test(file || ''); } catch (_) { return false; } });
+}
+
+// A Cell is SENSITIVE — never auto-approvable — if it is code-pinned or marked sensitive in its
+// spec. This is the COOPERATIVE signal (AI-writable, so an agent could strip it — visible in the
+// ratification spec-diff). The AUTHORITATIVE backstop is the owner-signed policy `delegable:false`
+// (see grantCoversCell's `nonDelegable` check), which lives outside the delegated surface.
+function isSensitive(cell) {
+  if (!cell) return true;
+  const sp = cell.spec || {};
+  if (cell.codePin || sp.codePin || sp['code-pin'] || sp['code_pin']) return true;
+  const s = sp.sensitive;
+  return s === true || s === 'yes' || s === 'true';
+}
+
+// ── Default security guard ────────────────────────────────────────────────────
+// A grant refuses to auto-approve high-stakes areas — auth, payments, secrets, deploy,
+// CI/infra — UNLESS the human explicitly lifts the guard when issuing the grant
+// (`--no-guard` → envelope.guard === false). Matched on the Cell's file path OR its tags,
+// so it catches the usual layouts without any per-project setup. It's a DEFAULT DENY layered
+// on top of the human's own allow/deny/tag scope: freedom by default, but never over the
+// dangerous surface unless the human says so. Patterns live in the (trusted) verifier so the
+// guard improves for existing grants; the signed envelope records only the on/off intent.
+// "auth" alone is deliberately excluded so it doesn't snag "author"; the stems below do.
+const GUARD_PATH = /(authentic|authoriz|oauth|login|signin|\bsession|password|passwd|credential|permission|rbac|secret|apikey|api[-_]?key|\btoken|\.env|keystore|private[-_]?key|payment|billing|checkout|invoice|stripe|paypal|subscription|\bcharge|deploy|release|migrat|terraform|\.tf(\b|$)|dockerfile|docker-compose|kubernet|\bk8s\b|helm|[\\/]infra|\.github[\\/]|\.gitlab|workflow|pipeline|jenkins|circleci|[\\/]ci[\\/])/i;
+const GUARD_TAGS = new Set(['auth', 'authentication', 'authorization', 'security', 'payment', 'payments', 'billing', 'secret', 'secrets', 'deploy', 'deployment', 'release', 'ci', 'cd', 'infra', 'infrastructure']);
+// Does a Cell fall under the default security guard (auth/payments/secrets/deploy/CI)?
+function matchesGuard(cell) {
+  if (!cell) return false;
+  if (GUARD_PATH.test(String(cell.file || ''))) return true;
+  try { return cellTags(cell).some((t) => GUARD_TAGS.has(t)); } catch (_) { return false; }
+}
+
+// The risk level a Cell declares (`risk: low|medium|high`), defaulting to medium when unstated.
+function cellRisk(cell) { return String(((cell && cell.spec) || {}).risk || 'medium').toLowerCase(); }
+
+// Does a grant's envelope cover this Cell? opts.policy (owner-signed) supplies the authoritative
+// non-delegable backstop. Returns a { ok, reason } so the verifier can explain a refusal.
+function grantCoversCellR(grant, cellId, cell, opts) {
+  if (!grant) return { ok: false, reason: 'no grant' };
+  const policy = (opts && opts.policy) || { rules: [] };
+  if (nonDelegable(policy, cell || { file: '', spec: {} })) return { ok: false, reason: 'owner-signed policy marks this area non-delegable — needs a real human signature' };
+  if (isSensitive(cell)) return { ok: false, reason: 'Cell is sensitive/code-pinned — needs a real human signature' };
+  const env = envelopeOf(grant);
+  if (env.guard && matchesGuard(cell)) return { ok: false, reason: `matches the grant's default security guard (auth/payments/secrets/deploy/CI) — needs a real human signature (issue the grant with --no-guard to lift)` };
+  if (env.cells.length && !env.cells.includes(cellId)) return { ok: false, reason: 'Cell is not in the grant cell allow-list' };
+  const file = (cell && cell.file) || '';
+  if (env.deny.length && pathMatchesAny(env.deny, file)) return { ok: false, reason: `path is in the grant's deny list` };
+  const allowM = pathMatchesAny(env.allow, file);
+  if (allowM === false) return { ok: false, reason: `path is outside the grant's allowed paths` };
+  if (env.denyTags.length || env.allowTags.length) {
+    let tags = []; try { tags = cellTags(cell); } catch (_) { tags = []; }
+    if (env.denyTags.length && tags.some((t) => env.denyTags.includes(t))) return { ok: false, reason: `Cell tag is in the grant's deny-tags` };
+    if (env.allowTags.length && !tags.some((t) => env.allowTags.includes(t))) return { ok: false, reason: `Cell tag is outside the grant's allow-tags` };
+  }
+  if (env.maxRisk && riskRank(cellRisk(cell)) > riskRank(env.maxRisk)) return { ok: false, reason: `Cell risk (${cellRisk(cell)}) exceeds the grant's max risk (${env.maxRisk})` };
+  return { ok: true };
+}
+// Boolean convenience (back-compat with existing callers).
+function grantCoversCell(grant, cellId, cell, opts) { return grantCoversCellR(grant, cellId, cell, opts).ok; }
+
+// ── child-grant attenuation ────────────────────────────────────────────────────
+// Every constraint of a child must be ⊆ its parent. Returns { ok, reason }.
+function attenuates(child, parent) {
+  const c = envelopeOf(child), p = envelopeOf(parent);
+  // allow: every child allow path must be inside SOME parent allow (or parent unrestricted).
+  if (p.allow.length) {
+    if (!c.allow.length) return { ok: false, reason: 'child must restrict allowed paths (parent is path-scoped)' };
+    for (const a of c.allow) { if (pathMatchesAny(p.allow, sampleOf(a)) === false) return { ok: false, reason: `child allow "${a}" is outside parent allow` }; }
+  }
+  // deny: child must inherit (⊇) every parent deny.
+  for (const d of p.deny) { if (!c.deny.includes(d)) return { ok: false, reason: `child must keep parent deny "${d}"` }; }
+  // security guard: a child may never LIFT a guard the parent kept on.
+  if (p.guard && !c.guard) return { ok: false, reason: 'child cannot lift the parent grant\'s security guard' };
+  // deny-tags: child must inherit (⊇) every parent deny-tag.
+  for (const t of p.denyTags) { if (!c.denyTags.includes(t)) return { ok: false, reason: `child must keep parent deny-tag "${t}"` }; }
+  // allow-tags: if the parent scoped to tags, the child's allow-tags must be a subset.
+  if (p.allowTags.length) { for (const t of c.allowTags) if (!p.allowTags.includes(t)) return { ok: false, reason: `child allow-tag "${t}" is outside parent allow-tags` }; }
+  // cells: if parent restricts to a cell list, child's must be a subset.
+  if (p.cells.length) { for (const id of c.cells) if (!p.cells.includes(id)) return { ok: false, reason: `child cell "${id}" is outside parent cells` }; }
+  // maxCount: child ≤ parent remaining.
+  if (parent.maxCount != null && (child.maxCount == null || child.maxCount > parent.maxCount)) return { ok: false, reason: 'child maxCount exceeds parent' };
+  // expiry: child ≤ parent.
+  if (parent.expiresAt && (!child.expiresAt || Date.parse(child.expiresAt) > Date.parse(parent.expiresAt))) return { ok: false, reason: 'child expiry is later than parent' };
+  // risk: child ≤ parent.
+  if (p.maxRisk && riskRank(c.maxRisk || 'high') > riskRank(p.maxRisk)) return { ok: false, reason: 'child max risk exceeds parent' };
+  // depth: parent must allow children.
+  if (!p.childGrants.allowed) return { ok: false, reason: 'parent does not permit child grants' };
+  return { ok: true };
+}
+// A representative concrete path for a child allow-glob, so we can test containment against the
+// parent's globs (e.g. child "src/ui/**" → sample "src/ui/x" which parent "src/**" must match).
+function sampleOf(glob) { return String(glob).replace(/\*\*/g, 'x').replace(/\*/g, 'x'); }
+
+// Validate + summarise every grant in the append-only log against the owner keys, the clock,
+// revocations, the auto-approvals spent, AND (P3) the parent chain for child grants.
+function deriveGrants(glog, ownerPubs, lockApprovals, nowMs) {
+  const now = nowMs || Date.now();
+  const events = (glog && glog.events) || [];
+  const revokeAt = {};
+  for (const e of events) if (e.type === 'grant-revoke' && e.grant) revokeAt[e.grant] = e.at;
+  const autos = {};
+  for (const a of (lockApprovals || [])) if (a.autoApproved && a.grant) (autos[a.grant] = autos[a.grant] || []).push(a);
+  for (const g of Object.keys(autos)) autos[g].sort((x, y) => String(x.at).localeCompare(String(y.at)));
+
+  const grantEvents = events.filter((e) => e.type === 'grant');
+  const byId = {};
+  for (const e of grantEvents) byId[e.id] = e;
+  const out = {};
+
+  // Depth-ordered pass: a child validates against its (already-derived) parent. Parents have no
+  // `parent` field so they resolve first; children resolve once their parent is in `out`.
+  const pending = grantEvents.slice();
+  let guard = pending.length + 1;
+  while (pending.length && guard-- > 0) {
+    const still = [];
+    for (const e of pending) {
+      if (e.parent && !out[e.parent]) { still.push(e); continue; } // parent not derived yet
+      out[e.id] = deriveOne(e, out, ownerPubs, revokeAt, autos, now);
+    }
+    if (still.length === pending.length) { // unresolved parents (missing/cyclic) — mark invalid
+      for (const e of still) out[e.id] = deriveOne(e, out, ownerPubs, revokeAt, autos, now);
+      break;
+    }
+    pending.length = 0; pending.push(...still);
+  }
+  return out;
+}
+
+function deriveOne(e, out, ownerPubs, revokeAt, autos, now) {
+  const rAt = revokeAt[e.id] || null;
+  const spent = (autos[e.id] || []).length;
+  const expired = !!(e.expiresAt && Date.parse(e.expiresAt) <= now);
+  let ownerOk = false, chain = null, attenuation = null;
+  if (e.parent) {
+    // Child: authority DESCENDS from the parent. It must be signed by the parent's grant key
+    // (issuedBy), the parent must be valid, and the child must strictly attenuate.
+    const parent = out[e.parent];
+    const parentValid = !!(parent && parent.ownerOk && !parent.revoked);
+    const sigOk = !!(parent && safeVerify(roster.eventBytes(e), e.signature, parent.grantPub) && (!e.issuedBy || e.issuedBy === parent.grantPub));
+    attenuation = parent ? attenuates(e, parent) : { ok: false, reason: 'parent grant not found' };
+    ownerOk = parentValid && sigOk && attenuation.ok;
+    chain = { parent: e.parent, parentValid, sigOk, attenuates: attenuation.ok, reason: attenuation.ok ? null : (sigOk ? attenuation.reason : 'child not signed by the parent grant key') };
+  } else {
+    // Root grant: must be validly OWNER-signed.
+    ownerOk = !!(e.signature && (ownerPubs || []).some((pub) => safeVerify(roster.eventBytes(e), e.signature, pub)));
+  }
+  // A parent's revocation cascades: a child is inactive once its parent is revoked/expired.
+  let parentInactive = false;
+  if (e.parent) { const pr = out[e.parent]; parentInactive = !pr || !pr.active; }
+  const active = ownerOk && !expired && !rAt && !parentInactive && (!e.maxCount || spent < e.maxCount);
+  return {
+    ...e, ownerOk, revokeAt: rAt, revoked: !!rAt, expired, spent,
+    remaining: e.maxCount ? Math.max(0, e.maxCount - spent) : null,
+    active, autos: autos[e.id] || [], envelope: envelopeOf(e), chain,
+  };
+}
+
+// The single active grant to auto-sign with right now (most recently issued that is active), or
+// null. `cells` (id → cell) lets us confirm all targets are in scope. opts.policy = owner-signed.
+function activeGrantFor(grants, targetIds, cells, opts) {
+  const list = Object.values(grants || {}).filter((g) => g.active)
+    .sort((a, b) => String(b.at).localeCompare(String(a.at)));
+  for (const g of list) {
+    if (g.maxCount && g.spent + targetIds.length > g.maxCount) continue; // would blow the count
+    if (targetIds.every((id) => grantCoversCell(g, id, cells[id], opts))) return g;
+  }
+  return null;
+}
+
+// Is THIS auto-approval of `cellId` acceptable under its grant? (verify does the actual signature
+// check with grant.grantPub; here we check the grant + window + envelope + count.)
+function autoApprovalOk(grant, approval, cellId, cell, opts) {
+  if (!grant) return { ok: false, reason: 'no such grant' };
+  if (!grant.ownerOk) return { ok: false, reason: grant.parent ? 'child grant does not validly chain to the owner root' : 'grant is not validly owner-signed' };
+  const at = Date.parse(approval.at) || 0;
+  if (Date.parse(grant.at) && at < Date.parse(grant.at)) return { ok: false, reason: 'approval predates the grant' };
+  if (grant.expiresAt && at > Date.parse(grant.expiresAt)) return { ok: false, reason: 'grant had expired' };
+  if (grant.revokeAt && at > Date.parse(grant.revokeAt)) return { ok: false, reason: 'grant was revoked before this approval' };
+  const cov = grantCoversCellR(grant, cellId, cell, opts);
+  if (!cov.ok) return { ok: false, reason: cov.reason };
+  if (grant.maxCount) {
+    const idx = (grant.autos || []).findIndex((a) => a.id === approval.id);
+    if (idx >= 0 && idx >= grant.maxCount) return { ok: false, reason: 'grant count exceeded' };
+  }
+  return { ok: true };
+}
+
+module.exports = {
+  isSensitive, matchesGuard, cellRisk, riskRank, envelopeOf, grantCoversCell, grantCoversCellR,
+  attenuates, deriveGrants, activeGrantFor, autoApprovalOk,
+};

package/src/history.js

@@ -0,0 +1,77 @@
+'use strict';
+// Reconstruct a Cell's spec + code AS IT WAS when a given Brief signed it, straight from git —
+// using the Brief's stored specHash as an exact, self-verifying anchor. Powers the Briefs-tab
+// "As signed / Current / What changed" view: a Brief is a point-in-time record, so opening a Cell
+// *through* it should show the version that was authorized, not today's. Read-only; needs git.
+const path = require('path');
+const cp = require('child_process');
+const { MARK_BEGIN, MARK_END, langOf } = require('./util');
+const { sha256 } = require('./crypto');
+const { parseSpec, grabUnitBody } = require('./extract');
+
+function git(dir, args) {
+  return cp.execFileSync('git', ['-C', dir, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+}
+function prefixBase(absFile) {
+  const dir = path.dirname(absFile), base = path.basename(absFile);
+  const prefix = git(dir, ['rev-parse', '--show-prefix']).trim(); // repo-root → file's dir (survives symlinked toplevels)
+  return { dir, rel: prefix + base };
+}
+function showAt(dir, rel, commit) {
+  try { return git(dir, ['show', commit + ':' + rel]); } catch (_) { return null; }
+}
+// The normalized marker-block for a Cell in raw content — byte-identical to extract.js, so
+// sha256(it) equals the stored specHash. Returns null if the Cell isn't present in that version.
+function normalizedBlock(content, cellId) {
+  const lines = String(content).split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const b = lines[i].match(MARK_BEGIN);
+    if (b && b[1] === cellId) {
+      const block = [lines[i]];
+      for (let j = i + 1; j < lines.length; j++) { block.push(lines[j]); if (MARK_END.test(lines[j])) return block.map((l) => l.replace(/\s+$/, '')).join('\n'); }
+      return null;
+    }
+  }
+  return null;
+}
+// Extract a Cell's spec block + code body from raw content at a given language family.
+function cellFromContent(content, cellId, family) {
+  const lines = String(content).split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const b = lines[i].match(MARK_BEGIN);
+    if (b && b[1] === cellId) {
+      const block = [lines[i]]; let end = -1;
+      for (let j = i + 1; j < lines.length; j++) { block.push(lines[j]); if (MARK_END.test(lines[j])) { end = j; break; } }
+      if (end === -1) return null;
+      const spec = parseSpec(block);
+      const unit = grabUnitBody(lines, end + 1, family);
+      return { spec, block: block.map((l) => l.replace(/\s+$/, '')).join('\n'), code: unit ? unit.body : null };
+    }
+  }
+  return null;
+}
+// Walk the file's history (newest→oldest, bounded) and return the version whose spec hashes to
+// signedHash — the exact thing the Brief sealed. { found, commit, at, block, code } | { found:false }.
+function cellAsSigned(root, file, cellId, signedHash, limit) {
+  const abs = path.resolve(root, file);
+  let dir, rel;
+  try { ({ dir, rel } = prefixBase(abs)); } catch (_) { return { found: false, reason: 'not a git repository' }; }
+  let commits;
+  try { commits = git(dir, ['log', '--format=%H %cI', '-n', String(limit || 200), '--', rel]).trim().split('\n').filter(Boolean); }
+  catch (_) { return { found: false, reason: 'no git history for this file' }; }
+  const family = langOf(abs);
+  for (const line of commits) {
+    const sp = line.indexOf(' ');
+    const commit = line.slice(0, sp), at = line.slice(sp + 1);
+    const content = showAt(dir, rel, commit);
+    if (content == null) continue;
+    const norm = normalizedBlock(content, cellId);
+    if (norm == null) continue;
+    if (sha256(norm) === signedHash) {
+      const cell = cellFromContent(content, cellId, family) || {};
+      return { found: true, commit: commit.slice(0, 10), at, block: cell.block || norm, code: cell.code || null };
+    }
+  }
+  return { found: false, reason: 'the signed version wasn’t found in this file’s git history' };
+}
+module.exports = { cellAsSigned, normalizedBlock, cellFromContent };

package/src/ids.js

@@ -0,0 +1,40 @@
+'use strict';
+// Cell-id scheme for distributed (multi-branch / multi-clone) work.
+//
+// The problem: a bare sequential counter (C-001, C-002…) assumes ONE writer — two branches mint
+// the same ids and collide on merge. And the id is part of the signed seal (items[id]=specHash),
+// so renumbering after the fact invalidates the seal. So we prevent collisions AT CREATION with a
+// short, stable per-CONTRIBUTOR shard: ids look like C-<shard>-<n> (e.g. C-3f2a-7). Two clones get
+// different shards → new cells from different people NEVER collide, no renumber, no re-sign.
+//
+// And numbers are MONOTONIC / never reused: `taken` includes every id that ever appeared in the
+// ledger, so a deleted feature's id is retired forever — an id always means one cell, like a git
+// commit hash. Deletions leave permanent gaps, which is correct for an audit trail.
+
+const C = require('./crypto');
+
+// A short shard derived from a seed — the signer/root key fingerprint when available (stable and
+// identity-tied), else random. 4 hex chars ≈ 65k space, so two contributors practically never coincide.
+function deriveShard(seed) {
+  const hex = C.sha256(String(seed == null ? ('r' + Date.now() + Math.random()) : seed));
+  return hex.slice(0, 4);
+}
+
+// Highest counter already used for `shard` across a set of ids (current cells ∪ ledger history).
+function maxForShard(ids, shard) {
+  let mx = 0; const re = new RegExp('^C-' + String(shard).replace(/[^a-z0-9]/gi, '') + '-(\\d+)$');
+  const each = (id) => { const m = String(id).match(re); if (m) { const v = parseInt(m[1], 10); if (v > mx) mx = v; } };
+  if (ids && typeof ids.forEach === 'function') ids.forEach(each); else for (const id of (ids || [])) each(id);
+  return mx;
+}
+
+// The next monotonic, sharded id. `taken` (a Set) should include current cell ids AND all historical
+// ledger ids, so a deleted-but-once-used id is never handed out again.
+function nextCellId(shard, taken) {
+  let n = maxForShard(taken, shard) + 1, id;
+  do { id = 'C-' + shard + '-' + n; n++; } while (taken && taken.has && taken.has(id));
+  if (taken && taken.add) taken.add(id);
+  return id;
+}
+
+module.exports = { deriveShard, maxForShard, nextCellId };