graphlin 0.1.2 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphlin",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Live architecture and activity diagrams from observable coding-agent work.",
   "private": false,
   "type": "module",
@@ -14,6 +14,7 @@
     "start": "node scripts/graphlin.mjs start",
     "demo": "node scripts/graphlin.mjs demo",
     "test": "node --test --test-timeout=30000",
+    "test:stress": "node --test --test-timeout=90000 tests/stress/*.mjs",
     "build": "node scripts/build-packages.mjs",
     "doctor": "node scripts/graphlin.mjs doctor",
     "eval:jev": "node scripts/evaluate-jev.mjs",
@@ -51,20 +52,24 @@
     "registry": "https://registry.npmjs.org/"
   },
   "files": [
-    "./LICENSE",
-    "./README.md",
-    "./plugin.json",
-    "./mcp.json",
-    "./.mcp.json",
     "./.claude-plugin/plugin.json",
     "./.codex-plugin/plugin.json",
+    "./.mcp.json",
+    "./LICENSE",
+    "./README.md",
     "./adapters/README.md",
     "./adapters/claude/hooks.json",
     "./adapters/claude/profile.json",
     "./adapters/codex/hooks.json",
     "./adapters/codex/profile.json",
     "./adapters/kiro/profile.json",
-    "./skills/graphlin/SKILL.md",
+    "./docs/decision-service.md",
+    "./docs/extension-authoring.md",
+    "./docs/model-api.md",
+    "./docs/usage.md",
+    "./docs/visualizer-views.md",
+    "./mcp.json",
+    "./plugin.json",
     "./runtime/collector/index.mjs",
     "./runtime/core/candidates.mjs",
     "./runtime/core/common.mjs",
@@ -80,21 +85,65 @@
     "./runtime/daemon/demo.mjs",
     "./runtime/daemon/diagnostics.mjs",
     "./runtime/daemon/export.mjs",
+    "./runtime/daemon/extension-api.mjs",
     "./runtime/daemon/ipc.mjs",
+    "./runtime/daemon/lineage.mjs",
     "./runtime/daemon/lock.mjs",
     "./runtime/daemon/manager.mjs",
+    "./runtime/daemon/model-api.mjs",
+    "./runtime/daemon/model-persistence.mjs",
     "./runtime/daemon/paths.mjs",
     "./runtime/daemon/persistence.mjs",
     "./runtime/daemon/server.mjs",
     "./runtime/daemon/settings.mjs",
+    "./runtime/decisions/broker.mjs",
+    "./runtime/decisions/contracts.mjs",
+    "./runtime/decisions/evaluation.mjs",
+    "./runtime/decisions/faults.mjs",
+    "./runtime/decisions/index.mjs",
+    "./runtime/decisions/profiles.mjs",
+    "./runtime/decisions/questions.mjs",
+    "./runtime/discovery/index.mjs",
+    "./runtime/discovery/inventory.mjs",
+    "./runtime/discovery/parser.mjs",
+    "./runtime/discovery/structure.mjs",
+    "./runtime/extensions/contracts.mjs",
+    "./runtime/extensions/frame.mjs",
+    "./runtime/extensions/index.mjs",
+    "./runtime/extensions/manifest.mjs",
+    "./runtime/extensions/packages.mjs",
+    "./runtime/extensions/profiles.mjs",
+    "./runtime/extensions/projection.mjs",
+    "./runtime/extensions/registry.mjs",
+    "./runtime/extensions/scene.mjs",
+    "./runtime/extensions/sdk.d.ts",
+    "./runtime/extensions/sdk.mjs",
     "./runtime/jev/fixture.mjs",
     "./runtime/jev/index.mjs",
+    "./runtime/jev/provider.mjs",
     "./runtime/jev/questions.mjs",
     "./runtime/jev/wire.mjs",
+    "./runtime/model/changes.mjs",
+    "./runtime/model/history.mjs",
+    "./runtime/model/index.mjs",
+    "./runtime/model/project-model.mjs",
+    "./runtime/model/records.mjs",
     "./runtime/pipeline.mjs",
+    "./runtime/platform.mjs",
+    "./runtime/visualizers/blocks.mjs",
+    "./runtime/visualizers/c4.mjs",
+    "./runtime/visualizers/changes.mjs",
+    "./runtime/visualizers/code.mjs",
+    "./runtime/visualizers/index.mjs",
+    "./runtime/visualizers/structure.mjs",
+    "./runtime/visualizers/timeline.mjs",
     "./runtime/web/app.js",
+    "./runtime/web/extension-frame.js",
     "./runtime/web/index.html",
     "./runtime/web/layout.js",
+    "./runtime/web/model-client.js",
+    "./runtime/web/platform.js",
+    "./runtime/web/scene.js",
     "./runtime/web/sidebar.js",
     "./runtime/web/sketch.js",
     "./runtime/web/style.css",
@@ -108,8 +157,24 @@
     "./scripts/collector.mjs",
     "./scripts/control.mjs",
     "./scripts/daemon.mjs",
+    "./scripts/extensions.mjs",
     "./scripts/graphlin.mjs",
     "./scripts/onboarding.mjs",
-    "./scripts/validate-packages.mjs"
-  ]
+    "./scripts/validate-packages.mjs",
+    "./skills/graphlin/SKILL.md"
+  ],
+  "dependencies": {
+    "@vscode/tree-sitter-wasm": "0.3.1"
+  },
+  "bundledDependencies": [
+    "@vscode/tree-sitter-wasm"
+  ],
+  "exports": {
+    "./extensions/sdk": {
+      "types": "./runtime/extensions/sdk.d.ts",
+      "import": "./runtime/extensions/sdk.mjs",
+      "default": "./runtime/extensions/sdk.mjs"
+    },
+    "./extensions/scene": "./runtime/extensions/scene.mjs"
+  }
 }

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "graphlin",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Local architecture and activity diagrams from observable coding-agent work.",
   "extensions": {
     "com.openai": {
@@ -11,7 +11,9 @@
         "longDescription": "A local viewer with passive event collection, explicit source-sharing controls, and an offline fixture demo.",
         "developerName": "Graphlin contributors",
         "category": "Productivity",
-        "defaultPrompt": ["Start Graphlin for this project in metadata-only mode."],
+        "defaultPrompt": [
+          "Start Graphlin for this project in metadata-only mode."
+        ],
         "brandColor": "#20BFA9"
       },
       "hooks": "./adapters/codex/hooks.json"

package/runtime/core/evidence.mjs

@@ -9,13 +9,16 @@ const fingerprint = stat => [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.c
 
 export class EvidenceStore {
   #root; #inputRoot; #policy; #records = new Map(); #byId = new Map();
-  constructor({ projectRoot, policy } = {}) {
+  #maxTrackedPaths; #reconcileCursor = 0; #lineage = null; #generationFloor;
+  constructor({ projectRoot, policy, maxTrackedPaths = LIMITS.trackedPaths, generationFloor = 0 } = {}) {
     try {
       this.#inputRoot = path.resolve(projectRoot);
       this.#root = realpathSync(projectRoot);
       if (!statSync(this.#root).isDirectory()) fail();
     } catch { fail('INVALID_PROJECT_ROOT'); }
     this.#policy = createPolicy(policy);
+    this.#maxTrackedPaths = integer(maxTrackedPaths, 1, 20000) ? maxTrackedPaths : LIMITS.trackedPaths;
+    this.#generationFloor = integer(generationFloor, 0, Number.MAX_SAFE_INTEGER - 1) ? generationFloor : 0;
   }
 
   #locator(input) {
@@ -43,17 +46,26 @@ export class EvidenceStore {
     }
     const parts = locator.relative.split('/');
     let current = this.#root;
+    let finalStat;
     try {
       if (await realpath(this.#root) !== this.#root) return this.#unavailable('root_changed');
       for (const part of parts) {
         current = path.join(current, part);
         const stat = await lstat(current, { bigint: true });
         if (stat.isSymbolicLink()) return this.#unavailable(`symlink:${fingerprint(stat)}`);
+        finalStat = stat;
       }
     } catch (error) {
       return absent(error) ? { status: 'missing', exists: false, complete: true, hash: null, text: null, stamp: 'missing' }
         : this.#unavailable('unreadable');
     }
+    // Metadata consent permits names/stat observations, never content reads or
+    // hashes. A local-source grant is distinct from permission to transmit it.
+    if (!this.#policy.readSource) {
+      if (!finalStat?.isFile()) return this.#unavailable('not_file');
+      return { status: 'present', exists: true, complete: true,
+        hash: null, text: null, stamp: fingerprint(finalStat) };
+    }
     let handle;
     try {
       // NOFOLLOW closes the final-component race. Revalidate the complete path
@@ -83,7 +95,7 @@ export class EvidenceStore {
       if (text.includes('\0')) return { status: 'partial', exists: true, complete: false, hash: hash(bytes), text: null, stamp };
       return {
         status: 'present', exists: true, complete: true, hash: hash(bytes),
-        text: this.#policy.transmitSource && !privateText(text) ? text : null, stamp,
+        text: !privateText(text) ? text : null, stamp,
       };
     } catch {
       // A disappearing/racing file during open/read is uncertainty. A subsequent
@@ -106,9 +118,9 @@ export class EvidenceStore {
   async #captureOne(locator) {
     const observed = await this.#inspect(locator);
     const previous = this.#records.get(locator.relative);
-    const version = hash([observed.status, observed.hash, observed.stamp]);
+    const version = hash([this.#lineage, observed.status, observed.hash, observed.stamp]);
     const id = opaque('artifact', this.#root, locator.relative);
-    const generation = previous ? previous.generation + (previous.version !== version ? 1 : 0) : 1;
+    const generation = previous ? previous.generation + (previous.version !== version ? 1 : 0) : this.#generationFloor + 1;
     const artifact = {
       id, path: locator.absolute, relativePath: locator.relative,
       hash: observed.hash, generation, exists: observed.exists, status: observed.status,
@@ -116,7 +128,7 @@ export class EvidenceStore {
     };
     // Registry retains no source bytes; returned captures are immutable private
     // snapshots. All path/cache cardinalities are bounded.
-    const record = { ...locator, id, generation, hash: observed.hash, status: observed.status, version };
+    const record = { ...locator, id, generation, hash: observed.hash, status: observed.status, version, lineage: this.#lineage };
     this.#records.set(locator.relative, record);
     this.#byId.set(id, record);
     return freeze(artifact);
@@ -129,14 +141,35 @@ export class EvidenceStore {
       const locator = this.#locator(input);
       if (!locator || seen.has(locator.relative)) continue;
       seen.add(locator.relative);
-      if (!this.#records.has(locator.relative) && this.#records.size >= LIMITS.trackedPaths) continue;
+      if (!this.#records.has(locator.relative) && this.#records.size >= this.#maxTrackedPaths) continue;
       results.push(await this.#captureOne(locator));
     }
     return results;
   }
-  async reconcile() {
+  setLineage(id) {
+    if (typeof id !== 'string' || !/^[a-f0-9]{64}$/.test(id)) fail('INVALID_LINEAGE');
+    if (id === this.#lineage) return [];
+    this.#lineage = id;
+    // A checkout change invalidates in-flight references immediately. The next
+    // real capture advances each generation, even if its bytes are identical.
+    return [...this.#records.values()].map(record => ({
+      id: record.id, path: record.absolute, relativePath: record.relative,
+      generation: record.generation, hash: record.hash, status: 'unavailable',
+      complete: false, exists: null, text: null,
+    }));
+  }
+  async reconcile({ refs, limit } = {}) {
     const results = [];
-    for (const record of this.#records.values()) results.push(await this.#captureOne(record));
+    let records;
+    if (Array.isArray(refs)) {
+      records = [...new Set(refs.slice(0, LIMITS.trackedPaths).map(ref => this.#byId.get(ref.artifactId)).filter(Boolean))];
+    } else if (integer(limit, 1, this.#maxTrackedPaths)) {
+      const all = [...this.#records.values()];
+      const count = Math.min(limit, all.length);
+      records = Array.from({ length: count }, (_, index) => all[(this.#reconcileCursor + index) % all.length]);
+      this.#reconcileCursor = all.length ? (this.#reconcileCursor + count) % all.length : 0;
+    } else records = [...this.#records.values()];
+    for (const record of records) results.push(await this.#captureOne(record));
     return results;
   }
   isCurrent(refs) {
@@ -144,7 +177,8 @@ export class EvidenceStore {
     return refs.every(ref => {
       if (!plain(ref) || !isHash(ref.hash) || !integer(ref.generation, 1)) return false;
       const current = this.#byId.get(ref.artifactId);
-      return current?.status === 'present' && current.hash === ref.hash && current.generation === ref.generation;
+      return current?.status === 'present' && current.lineage === this.#lineage &&
+        current.hash === ref.hash && current.generation === ref.generation;
     });
   }
 }

package/runtime/core/graph.mjs

@@ -31,7 +31,8 @@ function validReference(ref) {
   if (!exactKeys(ref, REF, ['excerpt', 'sourceRef']) || !isId(ref.artifactId) || !isHash(ref.hash) ||
       !integer(ref.generation, 1) || !isId(ref.eventId) || !integer(ref.startLine, 1, 10000000) ||
       !integer(ref.endLine, ref.startLine, 10000000) || ref.endLine - ref.startLine >= LIMITS.snippetLines ||
-      !['source', 'public_intent'].includes(ref.sourceClass) || ref.basis !== 'jev_interpretation' ||
+      !['source', 'public_intent'].includes(ref.sourceClass) ||
+      !['jev_interpretation', 'decision_interpretation'].includes(ref.basis) ||
       (Object.hasOwn(ref, 'excerpt') && !safeText(ref.excerpt, LIMITS.excerptChars))) return false;
   if (ref.sourceClass === 'public_intent' && !ref.sourceRef) return false;
   if (ref.sourceRef) {
@@ -131,11 +132,11 @@ function makePatch(graph, operations, causedBy = []) {
     baseRevision: graph.revision, revision: graph.revision + 1, causedBy, operations,
   });
 }
-function sourceReference(candidate, event, policy) {
+function sourceReference(candidate, event, policy, basis = 'jev_interpretation') {
   const ref = {
     artifactId: candidate.artifactId, hash: candidate.hash, generation: candidate.generation, eventId: event.id,
     startLine: candidate.startLine, endLine: candidate.endLine, sourceClass: candidate.sourceClass,
-    basis: 'jev_interpretation', sourceRef: clone(candidate.sourceRef),
+    basis, sourceRef: clone(candidate.sourceRef),
   };
   if (policy.displayEvidence || policy.persistEvidence) {
     const excerpt = candidate.text.slice(0, LIMITS.excerptChars);
@@ -251,6 +252,10 @@ function compileAuditedDecision(graph, { event, decision, policy }, audit) {
       new Set(decision.edges.map(e => e?.proposalId)).size !== decision.edges.length) return audit.reject(decision, 'duplicate_judgments');
   if (!decision.nodes.every(n => validNodeJudgment(n, candidates)) ||
       !decision.edges.every(e => validEdgeJudgment(e, bundle, candidates))) return audit.reject(decision, 'invalid_judgments');
+  // The service supplies validated provider provenance. Older manual decisions
+  // omit it and keep the legacy basis; answers/candidates cannot select a basis.
+  const providerId = decision.provider?.id;
+  const basis = providerId && providerId !== 'jev' ? 'decision_interpretation' : 'jev_interpretation';
   const existingNodes = new Map(graph.nodes.map(n => [n.id, n]));
   const existingEdges = new Map(graph.edges.map(e => [e.id, e]));
   const admitted = new Map(), operations = [];
@@ -278,7 +283,7 @@ function compileAuditedDecision(graph, { event, decision, policy }, audit) {
     const classification = judgment.classification === 'accepted' && candidate.complete && !event.incomplete &&
       judgment.supportProbability >= 0.85 && judgment.roleProbability >= 0.8 && judgment.roleConfidence >= 0.6 ? 'accepted' : 'tentative';
     const index = projected.nodes.length;
-    const refs = mergeReferences(old?.sourceRefs ?? [], [sourceReference(candidate, event, policy)]);
+    const refs = mergeReferences(old?.sourceRefs ?? [], [sourceReference(candidate, event, policy, basis)]);
     const node = {
       id, label: candidate.label, kind: judgment.role, shape: ROLE_SHAPES[judgment.role],
       x: old?.x ?? 80 + (index % 6) * 220, y: old?.y ?? 80 + Math.floor(index / 6) * 140,
@@ -301,10 +306,10 @@ function compileAuditedDecision(graph, { event, decision, policy }, audit) {
       (ref.generation > c.generation || (old.validity !== 'current' && ref.generation === c.generation))))) {
       report('skipped', 'stale_generation'); continue;
     }
-    const refs = mergeReferences([], evidence.map(c => sourceReference(c, event, policy)));
+    const refs = mergeReferences([], evidence.map(c => sourceReference(c, event, policy, basis)));
     // Every relation retains all dependencies; never silently drop evidence
     // when the reference budget is exceeded.
-    if (refs.length !== new Set(evidence.map(c => refKey(sourceReference(c, event, policy)))).size) {
+    if (refs.length !== new Set(evidence.map(c => refKey(sourceReference(c, event, policy, basis)))).size) {
       report('skipped', 'reference_limit'); continue;
     }
     const classification = judgment.classification === 'accepted' && source.classification === 'accepted' &&

package/runtime/core/privacy.mjs

@@ -19,6 +19,7 @@ export function createPolicy(options = {}) {
       .filter(p => !DEFAULT_EXCLUDES.includes(p)).slice(0, 64) : []
   )])].sort();
   const fields = {
+    readSource: options.readSource === true || options.transmitSource === true,
     transmitSource: options.transmitSource === true,
     displayEvidence: options.displayEvidence !== false,
     persistEvidence: options.persistEvidence === true,

package/runtime/daemon/auth.mjs

@@ -10,12 +10,16 @@ export function createAuth({ origin, instanceId, now = Date.now }) {
     for (const [key, expires] of map) if (expires <= now()) map.delete(key);
     while (map.size >= 16) map.delete(map.keys().next().value);
   }
+  function validTransport(req) {
+    const hosts = req.rawHeaders.filter((value, index) => index % 2 === 0 && value.toLowerCase() === 'host');
+    return hosts.length === 1 && req.headers.host === new URL(origin).host &&
+      ['127.0.0.1', '::ffff:127.0.0.1'].includes(req.socket.remoteAddress);
+  }
   return {
     cookieName,
+    validTransport,
     validRequest(req, { mutation = false } = {}) {
-      const hosts = req.rawHeaders.filter((value, index) => index % 2 === 0 && value.toLowerCase() === 'host');
-      if (hosts.length !== 1 || req.headers.host !== new URL(origin).host) return false;
-      if (!['127.0.0.1', '::ffff:127.0.0.1'].includes(req.socket.remoteAddress)) return false;
+      if (!validTransport(req)) return false;
       if (req.headers['sec-fetch-site'] && !['same-origin', 'none'].includes(req.headers['sec-fetch-site'])) return false;
       if (mutation) return req.headers.origin === origin;
       return req.headers.origin === undefined || req.headers.origin === origin;

package/runtime/daemon/diagnostics.mjs

@@ -4,7 +4,7 @@ import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 import { CATEGORIES, KINDS, ROLES, RELATIONS, isId, opaque, plain } from '../core/common.mjs';
 import { createPolicy, excluded, privateText, safeLabel } from '../core/privacy.mjs';
-import { ACTIVITIES } from '../jev/questions.mjs';
+import { ACTIVITIES } from '../decisions/questions.mjs';
 import { runtimeError, uid } from './paths.mjs';
 
 export const DIAGNOSTIC_LIMITS = Object.freeze({

package/runtime/daemon/extension-api.mjs

@@ -0,0 +1,203 @@
+import {
+  createFrameDocument, getExtensionDataProjection, validateGrant, extensionId,
+  id, digest, integer, exact, uniqueStrings, jsonBytes, EXTENSION_LIMITS,
+} from '../extensions/index.mjs';
+import { safeText } from '../core/privacy.mjs';
+
+const PREFIX = '/api/extensions';
+const HTTP_ERROR = Symbol('extension_http_error');
+const fail = (status, code) => { throw Object.assign(new Error(code), { status, code, [HTTP_ERROR]: true }); };
+const sameGrant = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+
+function reply(res, status, value) {
+  const body = jsonBytes(value, EXTENSION_LIMITS.projectionBytes);
+  res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+  res.end(body);
+}
+async function bodyJSON(req) {
+  if (!/^application\/json(?:;\s*charset=utf-8)?$/i.test(req.headers['content-type'] ?? '')) fail(415, 'invalid_content_type');
+  if (req.headers['content-encoding']) fail(400, 'unsupported_content_encoding');
+  const chunks = [];
+  let size = 0;
+  const timer = setTimeout(() => req.destroy(), 2000);
+  try {
+    for await (const chunk of req) {
+      size += chunk.length;
+      if (size > 16 * 1024) fail(413, 'extension_request_limit');
+      chunks.push(chunk);
+    }
+    let value;
+    try { value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks))); }
+    catch { fail(400, 'invalid_json'); }
+    return value;
+  } finally { clearTimeout(timer); }
+}
+function parameters(query, allowed) {
+  const result = {};
+  for (const [name, value] of new URLSearchParams(query)) {
+    if (!allowed.includes(name) || Object.hasOwn(result, name) || !value) fail(400, 'invalid_extension_query');
+    result[name] = value;
+  }
+  for (const field of ['scope', 'session', 'checkpoint']) {
+    if (result[field] !== undefined && !id(result[field])) fail(400, 'invalid_extension_query');
+  }
+  if (result.nonce !== undefined && !/^[A-Za-z0-9_-]{24,128}$/.test(result.nonce)) fail(400, 'invalid_frame_nonce');
+  return result;
+}
+
+/**
+ * Parent performs loopback/Host/Origin checks and viewer-cookie authentication.
+ * Never pass viewerAuthorized for an external read bearer or an opaque origin.
+ * getSnapshot is synchronous and reapplies current core policy, like model-api.
+ */
+export function createExtensionAPI({ registry, getSnapshot, projectId, runAnalysis } = {}) {
+  if (!registry || typeof getSnapshot !== 'function' || !id(projectId) ||
+    (runAnalysis !== undefined && typeof runAnalysis !== 'function')) throw new TypeError('invalid_extension_api_options');
+
+  async function requireGrant(extension, expectedDigest) {
+    const value = await registry.getGrant(extension);
+    try { validateGrant(value); } catch { fail(403, 'extension_grant_denied'); }
+    if (!value.approved || value.projectId !== projectId || value.extensionId !== extension) fail(403, 'extension_grant_denied');
+    if (expectedDigest !== undefined && value.digest !== expectedDigest) fail(409, 'extension_digest_changed');
+    return value;
+  }
+  function snapshot(params, grant) {
+    // A session selector can address historical work even without a checkpoint.
+    if ((params.checkpoint || params.session) && !grant.history) fail(403, 'history_not_granted');
+    const raw = getSnapshot({
+      ...(params.scope ? { scopeId: params.scope } : {}),
+      ...(params.session ? { sessionId: params.session } : {}),
+      ...(params.checkpoint ? { checkpointId: params.checkpoint } : {}),
+      persistent: false,
+    });
+    if (!raw || typeof raw !== 'object' || raw.then || raw.projectId !== projectId) fail(503, 'invalid_model_snapshot');
+    const projected = getExtensionDataProjection(
+      params.checkpoint ? { ...raw, checkpointId: params.checkpoint, replay: true } : raw, grant);
+    if (!projected) fail(403, 'extension_grant_denied');
+    return projected;
+  }
+  async function unchanged(extension, prior) {
+    const current = await requireGrant(extension, prior.digest);
+    if (!sameGrant(prior, current)) fail(403, 'extension_grant_changed');
+    return current;
+  }
+  async function analyze(req, res) {
+    const input = await bodyJSON(req);
+    if (!exact(input, ['id', 'digest', 'profileId', 'entityIds', 'revision']) ||
+      !extensionId(input.id) || !digest(input.digest) || !id(input.profileId) ||
+      !uniqueStrings(input.entityIds, id, 256) || !input.entityIds.length || !integer(input.revision)) {
+      fail(400, 'invalid_analysis_request');
+    }
+    const grant = await requireGrant(input.id, input.digest);
+    if (!grant.profiles?.includes(input.profileId)) fail(403, 'analysis_profile_not_granted');
+    const installed = await registry.getAssets(input.id, { digest: input.digest });
+    if (!installed.manifest.capabilities.includes('analysis.request')) fail(403, 'analysis_not_granted');
+    const profile = installed.profiles.find(value => value.id === input.profileId);
+    if (!profile) fail(403, 'analysis_profile_not_granted');
+    if (profile.selectors.fields.some(field => !grant.fields.includes(field))) fail(403, 'analysis_field_not_granted');
+    await unchanged(input.id, grant);
+    const model = snapshot({}, grant);
+    if (model.revision !== input.revision) fail(409, 'analysis_revision_changed');
+    if (!input.entityIds.every(entityId => model.entities.some(value => value.id === entityId)) ||
+      (profile.selectors.candidateIds.length &&
+        !input.entityIds.every(entityId => profile.selectors.candidateIds.includes(entityId)))) fail(403, 'analysis_candidate_not_granted');
+    if (!runAnalysis) fail(501, 'extension_analysis_unavailable');
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    req.once('aborted', abort);
+    res.once('close', abort);
+    try {
+      // Core owns provider calls, source consent/filtering, approval capabilities,
+      // evidence-version checks, subscriptions, and recording interpretations.
+      const result = await runAnalysis({
+        projectId, extensionId: input.id, digest: input.digest, profile,
+        entityIds: [...input.entityIds], revision: input.revision, grant, signal: controller.signal,
+      });
+      await unchanged(input.id, grant);
+      const current = snapshot({}, grant);
+      if (!result || !['accepted', 'pending', 'complete', 'unavailable'].includes(result.status)) fail(503, 'invalid_analysis_result');
+      const interpretationIds = Array.isArray(result.interpretationIds) ? result.interpretationIds.slice(0, 256)
+        .filter(value => id(value) && current.interpretations.some(item =>
+          item.id === value && item.namespace === profile.namespace)) : [];
+      if (!res.destroyed) reply(res, result.status === 'pending' || result.status === 'accepted' ? 202 : 200, {
+        status: result.status,
+        ...(id(result.requestId) && safeText(result.requestId, 160) ? { requestId: result.requestId } : {}),
+        interpretationIds: [...new Set(interpretationIds)],
+      });
+    } finally {
+      req.removeListener('aborted', abort);
+      res.removeListener('close', abort);
+    }
+  }
+  async function handle(req, res, { viewerAuthorized = false } = {}) {
+    if (typeof req.url !== 'string' ||
+      !(req.url === PREFIX || req.url.startsWith(`${PREFIX}/`) || req.url.startsWith(`${PREFIX}?`))) return false;
+    res.setHeader('Cache-Control', 'no-store');
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('Referrer-Policy', 'no-referrer');
+    try {
+      if (viewerAuthorized !== true || req.headers.origin === 'null') fail(401, 'viewer_authorization_required');
+      if (req.url.length > 4096 || /[\s\\#]/.test(req.url) || /%(?![a-f\d]{2})/i.test(req.url)) fail(400, 'invalid_extension_route');
+      const [pathname, query = '', ...extra] = req.url.split('?');
+      if (extra.length || pathname.includes('%') || pathname.includes('//') ||
+        pathname.split('/').some(part => part === '.' || part === '..')) fail(400, 'invalid_extension_route');
+      const route = pathname.slice(PREFIX.length);
+      const read = /^\/(data|frame)\/([^/]+)$/.exec(route);
+      if (read && !extensionId(read[2])) fail(400, 'invalid_extension_id');
+      const params = parameters(query, read?.[1] === 'data' ? ['scope', 'session', 'checkpoint'] :
+        read?.[1] === 'frame' ? ['nonce'] : []);
+      if (req.method === 'GET') {
+        if (req.headers['transfer-encoding'] || Number(req.headers['content-length'] ?? 0) !== 0) fail(400, 'unexpected_body');
+        if (route === '') { reply(res, 200, await registry.list()); return true; }
+        if (!read) fail(404, 'extension_route_not_found');
+        const extension = read[2];
+        const grant = await requireGrant(extension);
+        if (read[1] === 'data') {
+          reply(res, 200, snapshot(params, grant));
+        } else {
+          if (!params.nonce) fail(400, 'invalid_frame_nonce');
+          const assets = await registry.getAssets(extension, { digest: grant.digest });
+          await unchanged(extension, grant);
+          const frame = createFrameDocument({ ...assets, nonce: params.nonce });
+          // DENY remains on every other route. Response CSP sandboxing and
+          // frame-ancestors 'self' protect the directly opened frame document.
+          res.removeHeader('X-Frame-Options');
+          for (const [name, value] of Object.entries(frame.headers)) res.setHeader(name, value);
+          res.writeHead(200); res.end(frame.body);
+        }
+        return true;
+      }
+      if (req.method !== 'POST') fail(405, 'extension_method_not_allowed');
+      if (route === '/analysis') { await analyze(req, res); return true; }
+      if (!['/grant', '/revoke'].includes(route)) fail(404, 'extension_route_not_found');
+      const input = await bodyJSON(req);
+      if (route === '/grant') {
+        if (!exact(input, ['id', 'digest', 'fields', 'history', 'approved'], ['profiles']) ||
+          !extensionId(input.id)) fail(400, 'invalid_extension_grant');
+        const { id: extension, ...request } = input;
+        reply(res, 200, await registry.grant(extension, request));
+      } else {
+        if (!exact(input, ['id']) || !extensionId(input.id)) fail(400, 'invalid_extension_revoke');
+        reply(res, 200, await registry.revoke(input.id));
+      }
+    } catch (error) {
+      const known = {
+        extension_not_installed: [404, 'extension_not_installed'],
+        extension_digest_changed: [409, 'extension_digest_changed'],
+        unrequested_data_field: [403, 'unrequested_data_field'],
+        unrequested_profile: [403, 'unrequested_profile'],
+        unrequested_history: [403, 'unrequested_history'],
+        unrequested_analysis: [403, 'unrequested_analysis'],
+        invalid_extension_grant: [400, 'invalid_extension_grant'],
+        MODEL_CHECKPOINT_UNAVAILABLE: [404, 'checkpoint_unavailable'],
+        MODEL_SCOPE_UNAVAILABLE: [404, 'scope_unavailable'],
+      }[error?.code];
+      const status = error?.[HTTP_ERROR] ? error.status : known?.[0] ?? 503;
+      const code = error?.[HTTP_ERROR] ? error.code : known?.[1] ?? 'extension_unavailable';
+      if (!res.headersSent && !res.destroyed) reply(res, status, { error: code });
+      else if (!res.destroyed) res.destroy();
+    }
+    return true;
+  }
+  return { handle };
+}

package/runtime/daemon/lineage.mjs

@@ -0,0 +1,70 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { safeText } from '../core/privacy.mjs';
+
+const TTL_MS = 2000;
+const CONTROLS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/;
+const BRANCH = ['symbolic-ref', '--quiet', '--short', 'HEAD'];
+const HEAD = ['rev-parse', '--verify', '--end-of-options', 'HEAD'];
+const validBranch = value => safeText(value, 240) && !CONTROLS.test(value) &&
+  !/[<>\\:\s]/.test(value) && !value.startsWith('/') && !value.startsWith('-');
+
+/** Local ref metadata only. The caller owns reconciliation and model updates. */
+export function createLineageReader({ projectRoot, projectId, execute = execFile } = {}) {
+  if (typeof projectRoot !== 'string' || !path.isAbsolute(projectRoot) ||
+      Buffer.byteLength(projectRoot) > 4096 || projectRoot.includes('\0') ||
+      typeof projectId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,159}$/.test(projectId) ||
+      typeof execute !== 'function') throw new TypeError('invalid_lineage_options');
+  let cached, expiresAt = 0, pending;
+  const result = (status, branch, head) => Object.freeze({
+    id: createHash('sha256').update(JSON.stringify([projectId, status, branch ?? null, head ?? null])).digest('hex'),
+    status, ...(branch ? { branch } : {}), ...(head ? { head } : {}),
+  });
+
+  function git(args) {
+    return new Promise(resolve => {
+      let child, settled = false;
+      const finish = value => { if (!settled) { settled = true; clearTimeout(timer); resolve(value); } };
+      const timer = setTimeout(() => {
+        finish({ status: 'unavailable' });
+        try { child?.kill?.('SIGKILL'); } catch { /* No child details leave the reader. */ }
+      }, 800);
+      try {
+        child = execute('git', ['-c', 'core.fsmonitor=false', '-c', 'core.hooksPath=/dev/null', ...args], {
+          cwd: projectRoot, shell: false, timeout: 750, killSignal: 'SIGKILL', maxBuffer: 4096, encoding: 'utf8',
+          env: { PATH: process.env.PATH || '/usr/bin:/bin', LC_ALL: 'C',
+            GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null',
+            GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0', GIT_NO_REPLACE_OBJECTS: '1', GIT_NO_LAZY_FETCH: '1' },
+        }, (error, stdout, stderr) => {
+          const text = typeof stdout === 'string' ? stdout.replace(/\r?\n$/, '') : '';
+          if (!error) return finish({ status: 'ok', text });
+          if (!error.killed && error.code === 1 && !text && args === BRANCH) return finish({ status: 'detached' });
+          finish({ status: !error.killed && error.code === 128 && typeof stderr === 'string' &&
+            stderr.includes('not a git repository') ? 'not_git' : 'unavailable' });
+        });
+      } catch { finish({ status: 'unavailable' }); }
+    });
+  }
+
+  async function readRefs() {
+    if (CONTROLS.test(projectRoot)) return result('unavailable');
+    const branch = await git(BRANCH);
+    if (branch.status === 'not_git') return result('not_git');
+    if (branch.status !== 'detached' && (branch.status !== 'ok' || !validBranch(branch.text))) return result('unavailable');
+    const head = await git(HEAD);
+    if (head.status !== 'ok' || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(head.text)) return result('unavailable');
+    // Do not combine a branch observed before checkout with another branch's HEAD.
+    const after = await git(BRANCH);
+    if (branch.status !== after.status || branch.text !== after.text) return result('unavailable');
+    return result('git', branch.status === 'ok' ? branch.text : undefined, head.text);
+  }
+
+  return async function read() {
+    if (cached && Date.now() < expiresAt) return cached;
+    if (!pending) pending = readRefs().then(value => {
+      cached = value; expiresAt = Date.now() + TTL_MS; return value;
+    }).finally(() => { pending = undefined; });
+    return pending;
+  };
+}