graphlin 0.2.0 → 0.2.1

package/runtime/architecture/controller.mjs

@@ -0,0 +1,209 @@
+const MAX_PENDING = 10_000;
+const BATCH_SIZE = 6;
+const STATES = new Set(['waiting', 'queued', 'running', 'complete', 'partial', 'unavailable']);
+const version = value => `${value.generation}:${value.hash}:${value.status}`;
+const metadata = value => ({
+  artifactId: value.id, generation: value.generation, hash: value.hash, status: value.status,
+});
+
+/** Coalesces observations. Captured source lives only for the active analysis job. */
+export function createArchitectureController({
+  snapshot, capture, commit, analyze, available = () => null, ready = () => true,
+  onChange = () => {}, onDiagnostic = () => {}, now = Date.now, settleMs = 300,
+}) {
+  const known = new Map(), pending = new Map(), completed = new Map();
+  const retries = new Map();
+  let state = 'waiting', reason = 'no_source', timer, active, abort, activeVersions;
+  let closed = false, epoch = 0, manual = false, omitted = 0, failures = 0, lastRunAt = null;
+
+  function status() {
+    const model = snapshot();
+    const supported = (model.interpretations ?? []).filter(value =>
+      value.namespace === 'graphlin.architecture' && value.validity === 'current' &&
+      value.support === 'supported' && value.classification === 'accepted');
+    const blocked = available();
+    return {
+      status: blocked ? 'unavailable' : state,
+      ...(blocked || reason ? { reason: blocked || reason } : {}),
+      applications: supported.filter(value => value.kind === 'application').length,
+      components: supported.filter(value => value.kind === 'component').length,
+      pending: pending.size, inspected: completed.size, total: known.size,
+      omitted, failures, ...(lastRunAt === null ? {} : { lastRunAt }),
+    };
+  }
+  function publish(next, why = null) {
+    state = STATES.has(next) ? next : 'unavailable';
+    reason = why;
+    try { onChange(); } catch { /* Observation must remain fail-open. */ }
+  }
+  function diagnostic(result) {
+    try {
+      onDiagnostic({
+        status: result.status, code: result.diagnostics?.code ?? 'architecture_unavailable',
+        analyzed: result.coverage?.analyzedArtifactIds?.length ?? 0,
+        deferred: result.coverage?.deferredArtifactIds?.length ?? 0,
+        providerRequests: result.diagnostics?.providerRequests ?? 0,
+      });
+    } catch { /* Diagnostics cannot prevent admission or shutdown. */ }
+  }
+  function enqueue(id, { force = false } = {}) {
+    const item = known.get(id);
+    if (!item || (!force && completed.get(id) === version(item))) return;
+    if (!pending.has(id) && pending.size >= MAX_PENDING) { omitted++; return; }
+    pending.set(id, item);
+  }
+  function wake() {
+    if (closed) return;
+    const blocked = available();
+    if (blocked) {
+      clearTimeout(timer); timer = null;
+      abort?.abort();
+      return;
+    }
+    if (active || timer || (!pending.size && !manual)) return;
+    timer = setTimeout(() => {
+      timer = null;
+      if (!ready()) { wake(); return; }
+      void run();
+    }, settleMs);
+    timer.unref?.();
+  }
+  function observe(artifacts) {
+    if (closed) return;
+    for (const artifact of artifacts) {
+      const item = metadata(artifact), old = known.get(artifact.id);
+      if (old && version(old) === version(item)) continue;
+      if (!old && known.size >= MAX_PENDING) { omitted++; continue; }
+      known.set(artifact.id, item);
+      completed.delete(artifact.id);
+      retries.delete(artifact.id);
+      enqueue(artifact.id);
+      if (activeVersions?.has(artifact.id) && activeVersions.get(artifact.id) !== version(item)) abort?.abort();
+    }
+    if (!active && pending.size) { state = 'queued'; reason = null; }
+    wake();
+  }
+  async function run() {
+    if (active || closed || available()) return active;
+    clearTimeout(timer); timer = null;
+    if (manual) {
+      retries.clear();
+      completed.clear();
+      omitted = 0;
+      for (const id of known.keys()) enqueue(id, { force: true });
+      manual = false;
+    }
+    if (!pending.size) { publish('waiting', 'no_source'); return; }
+    const ids = [...pending.keys()].slice(0, BATCH_SIZE), generation = epoch;
+    abort = new AbortController();
+    const signal = abort.signal;
+    publish('running');
+    active = (async () => {
+      const artifacts = await capture(ids);
+      if (closed || signal.aborted || generation !== epoch) return;
+      const captured = new Map(artifacts.map(value => [value.id, metadata(value)]));
+      activeVersions = new Map(ids.flatMap(id => known.has(id)
+        ? [[id, version(captured.get(id) ?? known.get(id))]] : []));
+      // Parsing can settle after a newer capture was observed. Never mark that
+      // newer version inspected using an older capture.
+      if (ids.some(id => activeVersions.get(id) !== version(known.get(id) ?? {}))) return;
+      const result = await analyze({ model: snapshot(), artifacts, affectedArtifactIds: ids, signal });
+      if (closed || signal.aborted || generation !== epoch) return;
+      diagnostic(result);
+      const applied = result.affectedEntityIds?.length || result.coverage?.missingArtifactIds?.length
+        ? await commit(result, { artifacts: artifacts.map(metadata), signal, epoch: generation })
+        : true;
+      if (closed || signal.aborted || generation !== epoch) return;
+      if (!applied || applied.accepted === false) {
+        // A source race may be retried, but a persistently rejected admission
+        // must not become an endless background classification loop.
+        for (const id of ids) {
+          if (activeVersions.get(id) !== version(known.get(id) ?? {})) continue;
+          const count = (retries.get(id) ?? 0) + 1;
+          retries.set(id, count);
+          if (count >= 2) { pending.delete(id); completed.set(id, activeVersions.get(id)); failures++; }
+        }
+        publish(pending.size ? 'queued' : 'partial', 'source_changed');
+        return;
+      }
+      if (Number.isSafeInteger(applied.omitted) && applied.omitted > 0) omitted += applied.omitted;
+      const deferred = new Set(result.coverage?.deferredArtifactIds ?? []);
+      const progressed = ids.some(id => !deferred.has(id));
+      for (const id of ids) {
+        if (activeVersions.get(id) !== version(known.get(id) ?? {})) continue;
+        pending.delete(id);
+        // Move budget-deferred captures to the back, so the next batch can
+        // spend its source budget on them. Stop if a whole batch made no
+        // progress (for example, no capture is available).
+        if (deferred.has(id) && progressed) continue;
+        completed.set(id, activeVersions.get(id));
+        if (deferred.has(id)) failures++;
+      }
+      for (const id of deferred) enqueue(id);
+      for (const id of result.coverage?.deferredMembershipArtifactIds ?? []) {
+        const count = retries.get(id) ?? 0;
+        if (count < 2) { retries.set(id, count + 1); enqueue(id, { force: true }); }
+        else if (count === 2) { retries.set(id, 3); omitted++; }
+      }
+      lastRunAt = now();
+      if (result.status === 'unavailable') { failures++; publish('unavailable', 'analysis_failed'); }
+      else if (result.status === 'partial' || omitted) publish('partial', 'partial_coverage');
+      else {
+        const totals = status();
+        publish('complete', totals.applications + totals.components ? null : 'none_supported');
+      }
+    })().catch(() => {
+      if (!closed && !signal.aborted) {
+        failures++;
+        for (const id of ids) {
+          if (activeVersions && activeVersions.get(id) !== version(known.get(id) ?? {})) continue;
+          pending.delete(id);
+          if (known.has(id)) completed.set(id, version(known.get(id)));
+        }
+        publish('unavailable', 'analysis_failed');
+      }
+    }).finally(() => {
+      active = null; abort = null; activeVersions = null;
+      if (!closed) {
+        if (pending.size || manual) { state = 'queued'; wake(); }
+        else if (state === 'running') publish(available() ? 'unavailable' : 'partial', available() || 'source_changed');
+      }
+    });
+    return active;
+  }
+  function request() {
+    if (!closed) {
+      manual = true;
+      publish('queued', available());
+      wake();
+    }
+    return status();
+  }
+  function invalidate() {
+    epoch++;
+    abort?.abort();
+    completed.clear();
+    retries.clear();
+    for (const id of known.keys()) enqueue(id, { force: true });
+    wake();
+  }
+  return {
+    observe, wake, request, status, invalidate,
+    async whenIdle() {
+      clearTimeout(timer); timer = null;
+      while (!closed && !available() && (active || pending.size || manual)) {
+        if (!ready()) break;
+        await (active ?? run());
+      }
+      clearTimeout(timer); timer = null;
+    },
+    async close() {
+      closed = true;
+      clearTimeout(timer); timer = null;
+      abort?.abort();
+      pending.clear();
+      await active;
+      known.clear(); completed.clear(); retries.clear();
+    },
+  };
+}

package/runtime/architecture/evidence.mjs

@@ -0,0 +1,108 @@
+import { isDeepStrictEqual } from 'node:util';
+import { LIMITS, hash, isHash, isId, integer, opaque } from '../core/common.mjs';
+import { createPolicy, metadataEvent, safeLabel, safeText } from '../core/privacy.mjs';
+import { buildCandidates } from '../core/candidates.mjs';
+import { id, references, relativePath } from '../model/records.mjs';
+import { ARCHITECTURE_NAMESPACE } from './profile.mjs';
+
+export const ARCHITECTURE_LIMITS = Object.freeze({
+  artifacts: 6, candidatesPerArtifact: 8, membershipChecks: 6,
+  sourceRefs: 16, guardRefs: 128, sourceBytes: 512 * 1024,
+});
+export const requireValue = value => { if (!value) throw new Error('architecture_input_invalid'); };
+export const lineageOf = model => model.coverage?.lineage?.id ?? model.projectId;
+export const recordId = (projectId, ...parts) => opaque('architecture', projectId, ...parts);
+
+export function indexModel(model, policy) {
+  requireValue(model?.schemaVersion === 2 && id(model.projectId) && integer(model.revision)
+    && !model.replay && model.checkpointId === undefined && id(lineageOf(model))
+    && Array.isArray(model.entities) && model.entities.length <= 20_000
+    && Array.isArray(model.relations) && model.relations.length <= 40_000
+    && Array.isArray(model.interpretations) && model.interpretations.length <= 512
+    && Array.isArray(model.coverage?.artifacts) && model.coverage.artifacts.length <= 10_000);
+  const entities = new Map(), artifacts = new Map(), byArtifact = new Map();
+  for (const artifact of model.coverage.artifacts) {
+    requireValue(id(artifact?.id) && !artifacts.has(artifact.id));
+    artifacts.set(artifact.id, artifact);
+  }
+  function currentRefs(value, max = ARCHITECTURE_LIMITS.sourceRefs) {
+    const refs = references(value, max);
+    if (!refs?.length || !isDeepStrictEqual(refs, value)) return null;
+    return refs.every(ref => {
+      const artifact = artifacts.get(ref.artifactId);
+      return ref.sourceClass !== 'public_intent' && artifact?.status === 'present'
+        && artifact.fresh === true && artifact.hash === ref.hash && artifact.generation === ref.generation
+        && relativePath(artifact.relativePath, policy);
+    }) ? refs : null;
+  }
+  for (const entity of model.entities) {
+    requireValue(id(entity?.id) && !entities.has(entity.id));
+    entities.set(entity.id, entity);
+    if (!byArtifact.has(entity.artifactId)) byArtifact.set(entity.artifactId, []);
+    if (entity.basis === 'parsed' && entity.validity === 'current' && entity.classification === 'accepted'
+      && safeLabel(entity.label) && currentRefs(entity.sourceRefs)) byArtifact.get(entity.artifactId).push(entity);
+  }
+  const relations = model.relations.filter(value => value?.validity === 'current'
+    && value.basis === 'parsed' && entities.has(value.source) && entities.has(value.target)
+    && ['contains', 'imports', 'calls', 'depends_on'].includes(value.kind) && currentRefs(value.sourceRefs));
+  return { entities, artifacts, byArtifact, relations, currentRefs };
+}
+
+export function moduleForArtifact(index, artifactId) {
+  const modules = (index.byArtifact.get(artifactId) ?? []).filter(entity => ['module', 'file'].includes(entity.kind));
+  return modules.length === 1 ? modules[0] : null;
+}
+
+export function requestedArtifacts(model, index, captures, affectedArtifactIds) {
+  const supplied = captures.map(value => value?.id);
+  requireValue(supplied.every(isId) && new Set(supplied).size === supplied.length);
+  if (affectedArtifactIds === undefined) return supplied;
+  requireValue(Array.isArray(affectedArtifactIds) && affectedArtifactIds.length <= 128
+    && affectedArtifactIds.every(isId) && new Set(affectedArtifactIds).size === affectedArtifactIds.length);
+  const seeds = new Set(affectedArtifactIds), requested = new Set(seeds);
+  // One-hop dependencies nominate source for reconsideration, never membership.
+  for (const relation of index.relations) {
+    const source = index.entities.get(relation.source).artifactId;
+    const target = index.entities.get(relation.target).artifactId;
+    if (seeds.has(source) && isId(target)) requested.add(target);
+    if (seeds.has(target) && isId(source)) requested.add(source);
+  }
+  // Existing groups can depend on a changed file even if an import disappeared.
+  for (const value of model.interpretations) {
+    if (value.namespace !== ARCHITECTURE_NAMESPACE || !Array.isArray(value.sourceRefs)
+      || value.sourceRefs.length > ARCHITECTURE_LIMITS.sourceRefs
+      || !value.sourceRefs.some(ref => seeds.has(ref.artifactId))) continue;
+    for (const ref of value.sourceRefs) if (isId(ref.artifactId)) requested.add(ref.artifactId);
+  }
+  return [...seeds, ...[...requested].filter(value => !seeds.has(value)).sort()];
+}
+
+export function candidatesForCapture(capture, index, event, policy) {
+  const current = index.artifacts.get(capture.id);
+  const anchor = moduleForArtifact(index, capture.id);
+  if (!anchor || !current || current.status !== 'present' || current.fresh !== true
+    || capture.status !== 'present' || capture.exists !== true || capture.complete !== true
+    || !isHash(capture.hash) || !integer(capture.generation, 1)
+    || current.hash !== capture.hash || current.generation !== capture.generation
+    || !relativePath(capture.relativePath, policy) || current.relativePath !== capture.relativePath
+    || typeof capture.text !== 'string' || Buffer.byteLength(capture.text) > LIMITS.fileBytes
+    || !safeText(capture.text, LIMITS.fileBytes) || hash(capture.text) !== capture.hash) return null;
+  const candidates = buildCandidates({ event, artifacts: [capture], policy });
+  return { anchor, candidates: candidates.slice(0, ARCHITECTURE_LIMITS.candidatesPerArtifact),
+    omitted: Math.max(0, candidates.length - ARCHITECTURE_LIMITS.candidatesPerArtifact),
+    sourceRef: { artifactId: capture.id, hash: capture.hash, generation: capture.generation } };
+}
+export function unionRefs(...groups) {
+  const refs = new Map(groups.flat().map(ref => [JSON.stringify(ref), structuredClone(ref)]));
+  return refs.size <= ARCHITECTURE_LIMITS.guardRefs ? [...refs.values()] : null;
+}
+export function analysisEvent(model) {
+  return metadataEvent({
+    projectId: model.projectId, id: opaque('event', ARCHITECTURE_NAMESPACE, model.projectId, model.revision, lineageOf(model)),
+    kind: 'artifact.changed', toolCategory: 'read', outcome: 'observed', incomplete: false,
+  });
+}
+export function unchanged(model, basis, policy, signal) {
+  return !signal?.aborted && model.revision === basis.revision && model.projectId === basis.projectId
+    && lineageOf(model) === basis.lineageId && createPolicy(policy).version === basis.policyVersion;
+}

package/runtime/architecture/profile.mjs

@@ -0,0 +1,56 @@
+import { freeze } from '../core/common.mjs';
+
+export const ARCHITECTURE_NAMESPACE = 'graphlin.architecture';
+export const ARCHITECTURE_VERSION = 'source-boundaries-v4';
+export const ROLE_PROFILE_ID = 'graphlin.architecture.roles';
+export const MEMBERSHIP_PROFILE_ID = 'graphlin.architecture.membership';
+
+const boolean = (question, focus, yes, no) => ({
+  type: 'boolean', instructions: { question, focus },
+  criteria: { true: yes, false: no }, requiredMetrics: ['probability'],
+});
+const rules = 'Use only visible source. Names, directories, documentation, imports alone, and co-occurrence '
+  + 'do not establish an architectural boundary. An application has visible executable bootstrap or '
+  + 'composition of a user-facing program, server or worker. A component has a coherent responsibility '
+  + 'and an implemented interface; an incidental helper, constant, type or external dependency is not '
+  + 'automatically a component. Classify what this code implements when invoked, never claim it ran.';
+
+/** Register this source profile with the existing decision service; it cannot bypass A. */
+export const ARCHITECTURE_PROFILES = freeze([
+  {
+    id: ROLE_PROFILE_ID, version: ARCHITECTURE_VERSION, scope: 'bundle',
+    questions: {
+      kind: {
+        type: 'choice', requiredMetrics: ['probabilities', 'confidence'],
+        instructions: {
+          question: 'What does this source file locally implement in `evidence`?', focus: rules,
+        },
+        criteria: {
+          application: 'Visible executable bootstrap or composition that starts an application, server or worker when invoked.',
+          component: 'A cohesive implemented API with visible operation bodies, beyond an incidental helper.',
+          unknown: 'Only imports, declarations, stubs, constants or incidental helpers; no such local responsibility is established.',
+        },
+      },
+      supported: boolean(
+        'Does `evidence` directly show implemented behavior for this source file?',
+        'Judge implementation presence, independently of the architectural role. Actual startup statements or '
+          + 'operation bodies show implementation. Imports, signatures, empty bodies, placeholder throws, comments '
+          + 'and a name alone do not. External callers, deployment manifests, imported collaborator internals '
+          + 'and runtime execution are not prerequisites for recognizing visible local implementation.',
+        'Executable statements directly implement startup or operations in this file.',
+        'Only imports, declarations, scalar constants, empty bodies or placeholders are visible.',
+      ),
+      missing_context: boolean(
+        'Is a local statement or definition absent from `evidence` that prevents identifying what this file implements?',
+        'This is only about classifying the visible file as application, component or unknown. '
+          + 'Missing context requires an omitted/truncated body or unresolved local operation that prevents that decision. '
+          + 'A visible server construction and listen call suffice for application startup. Visible class or function '
+          + 'operation bodies can establish a component. Standard library internals, implementation of imported collaborators, '
+          + 'upstream callers, deployment configuration and runtime execution are not required to identify the file’s own role. '
+          + 'A fully visible constant or helper can conclusively be unknown without missing context.',
+        'A necessary local body or statement is absent, so the file’s implemented responsibility cannot be identified.',
+        'Visible code suffices to support or reject an application/component role for this file.',
+      ),
+    },
+  },
+]);

package/runtime/daemon/server.mjs

@@ -19,6 +19,7 @@ import { exportSnapshot } from './export.mjs';
 import { createDiagnostics } from './diagnostics.mjs';
 import { createDashboardInfoProvider } from './dashboard-info.mjs';
 import { createLineageReader } from './lineage.mjs';
+import { ARCHITECTURE_PROFILES } from '../architecture/profile.mjs';
 
 const WEB = new URL('../web/', import.meta.url);
 const assets = new Map([
@@ -164,11 +165,11 @@ export async function startServer({ projectRoot, dataDir, policy: policyOptions,
     // Test/demo services are injected; this module never logs request bodies.
     const service = decisionService ?? createDecisionService({
       provider: decisionProvider ?? createJevProvider({ apiKey }),
-      materializeBundle, buildRelationProposals,
+      materializeBundle, buildRelationProposals, profiles: ARCHITECTURE_PROFILES,
       limits: { eventDeadlineMs: 5000 },
     });
     pipeline = createPipeline({ projectRoot: paths.projectRoot, policy, decisionService: service,
-      classificationDeadlineMs: 5000,
+      classificationDeadlineMs: 5000, missingKey,
       mode, restoredState: await persistence.load(), restoredModel: await modelPersistence.load(),
       onChange: notify, onDiagnostic: diagnostics.record });
     modelAPI = createModelAPI({ projectId: paths.projectId, getSnapshot: pipeline.getModelState,
@@ -218,6 +219,14 @@ export async function startServer({ projectRoot, dataDir, policy: policyOptions,
           return;
         }
         if (!auth.authorized(req)) return json(res, 401, { error: 'authentication_required' });
+        if (req.method === 'GET' && req.url === '/api/architecture') {
+          return json(res, 200, pipeline.getArchitectureStatus());
+        }
+        if (req.method === 'POST' && req.url === '/api/architecture/discover') {
+          const input = await bodyJSON(req);
+          if (Object.keys(input).length) return json(res, 400, { error: 'invalid_input' });
+          return json(res, 202, pipeline.discoverArchitecture());
+        }
         if (req.method === 'GET' && req.url === '/api/about') {
           try { return json(res, 200, await dashboardInfo()); }
           catch { return json(res, 503, { error: 'dashboard_info_unavailable' }); }

package/runtime/model/project-model.mjs

@@ -3,7 +3,7 @@ import { isDeepStrictEqual as equal } from 'node:util';
 import { integer, plain } from '../core/common.mjs';
 import {
   DEFAULT_LIMITS, id, token, label, key, byteSize, relativePath, currentPolicy,
-  references, classification, entityRecord, relationRecord, interpretationRecord, certificate,
+  references, classification, entityRecord, relationRecord, interpretationRecord, interpretationNamespace, certificate,
   activityRecord, lineageRecord, projectSnapshot, time,
 } from './records.mjs';
 import { compareCheckpoint } from './changes.mjs';
@@ -159,6 +159,31 @@ export function createProjectModel({ projectId, policy = {}, restoredState, limi
     if (!accepted) deferred.relations++;
     return accepted;
   }
+  function admitInterpretation(record) {
+    const old = interpretations.get(record.id), victims = [];
+    const delta = byteSize(record) - (weights.get(old) ?? 0);
+    let reclaimed = 0;
+    const fits = () => interpretations.size + (old ? 0 : 1) - victims.length <= limits.interpretations &&
+      bytes + historyBytes + delta - reclaimed <= limits.bytes;
+    if (record.namespace === 'graphlin.architecture') {
+      // Make room only when requested. Map order preserves first admission, so
+      // legacy eviction is deterministic and never displaces other boundaries.
+      for (const candidate of interpretations.values()) {
+        if (fits()) break;
+        if (candidate.namespace !== 'graphlin.legacy-role' || candidate.id === record.id) continue;
+        victims.push(candidate.id);
+        reclaimed += weights.get(candidate) ?? 0;
+      }
+    }
+    if (!fits()) { deferred.interpretations++; return false; }
+    for (const victim of victims) {
+      remove(interpretations, victim, 'interpretations');
+      deferred.interpretations++;
+    }
+    const accepted = put(interpretations, record.id, record, limits.interpretations, 'interpretations');
+    if (!accepted) deferred.interpretations++;
+    return accepted;
+  }
   function appendActivity(event, nextSequence = sequence) {
     const record = activityRecord(event, nextSequence, clock());
     if (!record) return;
@@ -534,21 +559,129 @@ export function createProjectModel({ projectId, policy = {}, restoredState, limi
     }
   }
 
+  function currentInterpretationRefs(refs) {
+    if (!currentRefs(refs)) return false;
+    const effective = currentPolicy(policy);
+    return refs.every(ref => {
+      const artifact = artifacts.get(ref.artifactId), cert = artifact.enumeration;
+      return (!artifact.relativePath || relativePath(artifact.relativePath, effective)) &&
+        (!ref.extractor || ref.extractor === cert?.extractor) &&
+        (!ref.extractorVersion || ref.extractorVersion === cert?.version) &&
+        (!ref.identityVersion || ref.identityVersion === cert?.identityVersion);
+    });
+  }
+  function prepareInterpretation(value) {
+    const record = interpretationRecord(value, limits.refs);
+    if (!record || record.entityIds.some(entityId => !entities.has(entityId))) return null;
+    const current = currentInterpretationRefs(record.sourceRefs) &&
+      record.entityIds.every(entityId => entities.get(entityId).validity === 'current');
+    if (record.support === 'supported' && !current) return null;
+    const storageId = interpretations.get(record.id)?.namespace === record.namespace
+      ? record.id : key('interpretation', projectId, record.namespace, record.id);
+    return { ...record, id: storageId, ...(record.sourceRefs.length && !current
+      ? { validity: 'stale', classification: 'stale' } : {}) };
+  }
+
   function observeInterpretations(values, { event } = {}) {
     if (!Array.isArray(values) || !currentPolicy(policy).readSource) return stats();
+    const before = mutations, oldDeferred = deferred.interpretations;
     for (const value of values.slice(0, limits.interpretations)) {
-      const record = interpretationRecord(value, limits.refs);
-      if (!record || record.entityIds.some(entityId => !entities.has(entityId))) continue;
-      if (record.support === 'supported' && (!currentRefs(record.sourceRefs) ||
-          record.entityIds.some(entityId => entities.get(entityId).validity !== 'current'))) continue;
-      const storageId = key('interpretation', projectId, record.namespace, record.id);
-      const normalized = { ...record, id: storageId, validity: record.sourceRefs.length && !currentRefs(record.sourceRefs) ? 'stale' : record.validity };
-      if (!put(interpretations, storageId, normalized, limits.interpretations, 'interpretations')) deferred.interpretations++;
-    }
-    commit('interpretations.observed', { sessionId: event?.sessionId });
+      const record = prepareInterpretation(value);
+      if (record) admitInterpretation(record);
+    }
+    if (mutations !== before || oldDeferred !== deferred.interpretations) {
+      commit('interpretations.observed', { sessionId: event?.sessionId });
+    }
     return stats();
   }
 
+  /**
+   * Replace a namespace, or only records touching the supplied entity/artifact
+   * scope. An explicit empty scope matches nothing; [] withdraws old boundaries.
+   * Batch guards allow up to 256 refs; each stored record still allows 16.
+   * Async callers should supply exact sourceRefs even for an empty answer.
+   * For confirmed missing artifacts, omit present-source refs only after the
+   * caller's serialized epoch/version check; an unguarded clear carries no version.
+   */
+  function replaceInterpretations(namespace, values, options = {}) {
+    const result = (accepted, changed = false, removed = 0, retained = 0) => ({
+      ...stats(), accepted, changed, removed, retained,
+    });
+    if (!interpretationNamespace(namespace) || !Array.isArray(values) || values.length > DEFAULT_LIMITS.interpretations ||
+        !plain(options) || !currentPolicy(policy).readSource) return result(false);
+    const scoped = options.affectedEntityIds !== undefined || options.artifactIds !== undefined;
+    const validIds = (values, limit) => Array.isArray(values) && values.length <= limit && values.every(value => id(value));
+    if (!validIds(options.affectedEntityIds ?? [], limits.entities) ||
+        !validIds(options.artifactIds ?? [], limits.artifacts)) return result(false);
+    const affected = new Set(options.affectedEntityIds ?? []), affectedArtifacts = new Set(options.artifactIds ?? []);
+    const matches = record => !scoped || record.entityIds.some(entityId =>
+      affected.has(entityId) || affectedArtifacts.has(entities.get(entityId)?.artifactId)) ||
+      record.sourceRefs.some(ref => affectedArtifacts.has(ref.artifactId));
+    if (options.sourceRefs !== undefined) {
+      const guards = references(options.sourceRefs, 256);
+      if (!guards || !currentInterpretationRefs(guards)) return result(false);
+      const guarded = new Set(guards.map(ref => ref.artifactId));
+      if ([...affectedArtifacts].some(artifactId => !guarded.has(artifactId)) ||
+          [...affected].some(entityId => entities.get(entityId)?.artifactId &&
+            !guarded.has(entities.get(entityId).artifactId))) return result(false);
+    }
+    // Validate the complete bounded answer before treating any omission as a
+    // withdrawal. A malformed or stale answer cannot erase a newer boundary.
+    const incoming = new Map();
+    for (const value of values) {
+      if (!plain(value) || value.namespace !== undefined && value.namespace !== namespace) return result(false);
+      const record = prepareInterpretation({ ...value, namespace });
+      if (!record || record.validity !== 'current' || !matches(record) || incoming.has(record.id) ||
+          record.entityIds.some(entityId => entities.get(entityId).validity !== 'current') ||
+          record.sourceRefs.length && !currentInterpretationRefs(record.sourceRefs)) return result(false);
+      const old = interpretations.get(record.id);
+      if (old && !matches(old)) return result(false);
+      incoming.set(record.id, record);
+    }
+    const obsolete = new Set([...interpretations.values()].filter(record =>
+      record.namespace === namespace && matches(record) && !incoming.has(record.id)).map(record => record.id));
+    const updates = [...incoming.values()].map(record => ({
+      record, delta: byteSize(record) - (weights.get(interpretations.get(record.id)) ?? 0),
+    }));
+    let plannedCount = interpretations.size - obsolete.size +
+      updates.filter(({ record }) => !interpretations.has(record.id)).length;
+    let plannedBytes = bytes + historyBytes + updates.reduce((sum, update) => sum + update.delta, 0);
+    for (const recordId of obsolete) plannedBytes -= weights.get(interpretations.get(recordId)) ?? 0;
+    const victims = [];
+    const fits = () => plannedCount <= limits.interpretations && plannedBytes <= limits.bytes;
+    if (namespace === 'graphlin.architecture') {
+      for (const record of interpretations.values()) {
+        if (fits()) break;
+        if (record.namespace !== 'graphlin.legacy-role' || obsolete.has(record.id) || incoming.has(record.id)) continue;
+        victims.push(record.id);
+        plannedCount--;
+        plannedBytes -= weights.get(record) ?? 0;
+      }
+    }
+    // Admission is all-or-nothing, including prospective legacy evictions.
+    // Capacity defers a valid answer; it must not withdraw supported old roles.
+    if (!fits()) {
+      deferred.interpretations += incoming.size;
+      commit('interpretations.replaced', { sessionId: options.event?.sessionId });
+      return result(true, true);
+    }
+    const before = mutations, oldDeferred = deferred.interpretations;
+    for (const recordId of obsolete) remove(interpretations, recordId, 'interpretations');
+    for (const recordId of victims) {
+      remove(interpretations, recordId, 'interpretations');
+      deferred.interpretations++;
+    }
+    // Shrink existing records first so intermediate writes also fit the plan.
+    updates.sort((a, b) => Number(a.delta > 0) - Number(b.delta > 0) ||
+      (a.record.id < b.record.id ? -1 : a.record.id > b.record.id ? 1 : 0));
+    for (const { record } of updates) {
+      put(interpretations, record.id, record, limits.interpretations, 'interpretations');
+    }
+    const changed = mutations !== before || oldDeferred !== deferred.interpretations;
+    if (changed) commit('interpretations.replaced', { sessionId: options.event?.sessionId });
+    return result(true, changed, obsolete.size, incoming.size);
+  }
+
   function decisionFreshness(value, sourceRefs, fresh) {
     if (!fresh) return 'stale';
     if (value.validity === 'retracted') return 'retracted';
@@ -618,9 +751,7 @@ export function createProjectModel({ projectId, policy = {}, restoredState, limi
           classification: entity.classification, version: '1', sessionId,
           support: validity !== 'current' ? 'unknown' : entity.classification === 'accepted' ? 'supported' : 'tentative',
         }, limits.refs);
-        if (interpretation && !put(interpretations, interpretation.id, interpretation, limits.interpretations, 'interpretations')) {
-          deferred.interpretations++;
-        }
+        if (interpretation) admitInterpretation(interpretation);
       }
     }
     for (const edge of (Array.isArray(graph.edges) ? graph.edges : []).slice(0, limits.relations)) {
@@ -883,7 +1014,7 @@ export function createProjectModel({ projectId, policy = {}, restoredState, limi
   }
   restore(restoredState);
   return Object.freeze({
-    observeInventory, observeStructure, invalidateArtifacts, observeLegacy, observeInterpretations,
+    observeInventory, observeStructure, invalidateArtifacts, observeLegacy, observeInterpretations, replaceInterpretations,
     recordActivity, setSessions, observeLineage, snapshot, checkpoint, changes, stats,
   });
 }

package/runtime/model/records.mjs

@@ -17,6 +17,8 @@ export const validity = value => ['current', 'stale', 'retracted'].includes(valu
 export const classification = value => ['accepted', 'tentative', 'unknown', 'stale', 'pending', 'abstained'].includes(value)
   ? value : 'unknown';
 export const basis = value => ['metadata', 'parsed', 'lexical', 'decision', 'legacy'].includes(value) ? value : 'legacy';
+export const interpretationNamespace = value => typeof value === 'string' &&
+  /^[a-z][a-z0-9_-]*(?:[.:][a-z0-9_-]+)+$/.test(value) && safeText(value, 80) ? value : null;
 export const byteSize = value => Buffer.byteLength(JSON.stringify(value));
 export const key = (prefix, ...parts) => opaque(prefix, ...parts);
 const version = value => typeof value === 'string' && value.length <= 256 &&
@@ -102,8 +104,7 @@ export function relationRecord(value, maxRefs) {
 }
 
 export function interpretationRecord(value, maxRefs) {
-  if (!plain(value) || !id(value.id) || typeof value.namespace !== 'string' ||
-      !/^[a-z][a-z0-9_-]*(?:[.:][a-z0-9_-]+)+$/.test(value.namespace) || !safeText(value.namespace, 80)) return null;
+  if (!plain(value) || !id(value.id) || !interpretationNamespace(value.namespace)) return null;
   const sourceRefs = references(value.sourceRefs ?? [], maxRefs);
   if (!sourceRefs || !Array.isArray(value.entityIds) || value.entityIds.length > 256 ||
       value.entityIds.some(value => !id(value))) return null;