@dzhechkov/harness-core 0.8.5 → 0.8.10

package/src/target-integrations.ts

@@ -0,0 +1,225 @@
+/** Exhaustive target companion policy and once-per-install manifest aggregation. */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { claudeIntegrationAdapter } from '@dzhechkov/adapter-claude';
+import {
+  INTEGRATION_MANIFEST_MAX_BYTES,
+  INTEGRATION_REGISTRATION_MAX_COUNT,
+  canonicalIntegrationJson,
+  integrationManifestDigest,
+  parseHarnessIntegrationManifestJson,
+  type HarnessIntegrationManifestV1,
+  type IntegrationComponent,
+  type IntegrationPlan,
+  type IntegrationReasonCode,
+  type IntegrationStatus,
+  type TargetIntegrationAdapter,
+} from '@dzhechkov/core';
+
+import { TARGET_NAMES, type TargetName } from './targets.js';
+
+export interface RegistrationObservation {
+  readonly id: string;
+  readonly scope: 'project' | 'user' | 'plugin';
+  readonly registered: boolean;
+  readonly approval?: 'pending' | 'approved' | 'unknown';
+  readonly ready?: boolean;
+}
+
+export interface IntegrationOutcome {
+  readonly target: TargetName;
+  readonly component: IntegrationComponent;
+  readonly status: IntegrationStatus;
+  readonly registrations: readonly RegistrationObservation[];
+  readonly carrier?: { readonly scope: 'project' | 'user' | 'plugin'; readonly path: string };
+  readonly runtimeVersion?: string;
+  readonly evidenceVersion?: string;
+  readonly reasonCode?: IntegrationReasonCode;
+  readonly remediation?: string;
+  /** True when carrier bytes may precede a failed live check or ownership-journal commit. */
+  readonly applied?: boolean;
+}
+
+export type IntegrationPolicyCell =
+  | { readonly disposition: 'receipt'; readonly reasonCode?: never; readonly receiptVersion: string }
+  | { readonly disposition: 'legacy-post-write'; readonly reasonCode: 'CURRENT_LIVE_CHECK_FAILED' }
+  | { readonly disposition: 'refused'; readonly reasonCode: IntegrationReasonCode };
+
+export interface TargetIntegrationPolicy {
+  readonly mcp: IntegrationPolicyCell;
+  readonly hooks: IntegrationPolicyCell;
+}
+
+const refusedAdapter = (target: TargetName): TargetIntegrationAdapter => ({
+  target,
+  plan(manifest): IntegrationPlan {
+    const refusals: IntegrationPlan['refusals'][number][] = [];
+    if (Object.keys(manifest.mcpServers ?? {}).length > 0) {
+      refusals.push({ component: 'mcp', reasonCode: TARGET_INTEGRATION_POLICY[target].mcp.reasonCode ?? 'NO_QUALIFYING_LIVE_RECEIPT', remediation: 'run dz integrations-verify for this exact target product and version' });
+    }
+    if ((manifest.hooks?.length ?? 0) > 0) {
+      refusals.push({ component: 'hooks', reasonCode: TARGET_INTEGRATION_POLICY[target].hooks.reasonCode ?? 'NO_QUALIFYING_LIVE_RECEIPT', remediation: 'run dz integrations-verify with a hook canary and negative control' });
+    }
+    return { fragments: [], refusals };
+  },
+});
+
+/** Closed 10×2 policy. No fallback/default is permitted. */
+export const TARGET_INTEGRATION_POLICY: Record<TargetName, TargetIntegrationPolicy> = {
+  'claude-code': {
+    mcp: { disposition: 'receipt', receiptVersion: '2.1.235' },
+    hooks: { disposition: 'refused', reasonCode: 'NO_ACTIVATION_RECEIPT' },
+  },
+  codex: {
+    mcp: { disposition: 'refused', reasonCode: 'PROJECT_CARRIER_NOT_OBSERVED' },
+    hooks: { disposition: 'legacy-post-write', reasonCode: 'CURRENT_LIVE_CHECK_FAILED' },
+  },
+  cursor: {
+    mcp: { disposition: 'refused', reasonCode: 'TARGET_BINARY_UNAVAILABLE' },
+    hooks: { disposition: 'refused', reasonCode: 'TARGET_BINARY_UNAVAILABLE' },
+  },
+  copilot: {
+    mcp: { disposition: 'refused', reasonCode: 'TARGET_BINARY_UNAVAILABLE' },
+    hooks: { disposition: 'refused', reasonCode: 'TARGET_BINARY_UNAVAILABLE' },
+  },
+  windsurf: {
+    mcp: { disposition: 'refused', reasonCode: 'PRODUCT_SURFACE_AMBIGUOUS' },
+    hooks: { disposition: 'refused', reasonCode: 'TARGET_BINARY_UNAVAILABLE' },
+  },
+  gemini: {
+    mcp: { disposition: 'refused', reasonCode: 'NO_QUALIFYING_LIVE_RECEIPT' },
+    hooks: { disposition: 'refused', reasonCode: 'NO_QUALIFYING_LIVE_RECEIPT' },
+  },
+  opencode: {
+    mcp: { disposition: 'refused', reasonCode: 'TARGET_BINARY_UNAVAILABLE' },
+    hooks: { disposition: 'refused', reasonCode: 'TARGET_BINARY_UNAVAILABLE' },
+  },
+  openclaude: {
+    mcp: { disposition: 'refused', reasonCode: 'PROJECT_CARRIER_NOT_DOCUMENTED' },
+    hooks: { disposition: 'refused', reasonCode: 'TARGET_BINARY_UNAVAILABLE' },
+  },
+  hermes: {
+    mcp: { disposition: 'refused', reasonCode: 'LIVE_PROBE_TIMEOUT' },
+    hooks: { disposition: 'refused', reasonCode: 'NO_ACTIVATION_RECEIPT' },
+  },
+  'agents-md': {
+    mcp: { disposition: 'refused', reasonCode: 'NO_RUNTIME_SURFACE' },
+    hooks: { disposition: 'refused', reasonCode: 'NO_RUNTIME_SURFACE' },
+  },
+};
+
+export const TARGET_INTEGRATIONS: Record<TargetName, TargetIntegrationAdapter> = Object.fromEntries(
+  TARGET_NAMES.map((target) => [target, target === 'claude-code' ? claudeIntegrationAdapter : refusedAdapter(target)]),
+) as Record<TargetName, TargetIntegrationAdapter>;
+
+export interface IntegrationManifestSource {
+  readonly skillId: string;
+  readonly skillDir: string;
+}
+
+export interface IntegrationManifestAggregate {
+  readonly manifest: HarnessIntegrationManifestV1 | undefined;
+  readonly digest: string | undefined;
+  readonly sourcePaths: readonly string[];
+}
+
+export class IntegrationManifestError extends Error {
+  readonly code = 'MANIFEST_INVALID';
+  constructor(readonly manifestPath: string, message: string) {
+    super(`${manifestPath}: ${message}`);
+    this.name = 'IntegrationManifestError';
+  }
+}
+
+/** Load, validate and aggregate every adjacent manifest before target effects. */
+export function aggregateIntegrationManifests(
+  sources: readonly IntegrationManifestSource[],
+): IntegrationManifestAggregate {
+  const manifests: { path: string; value: HarnessIntegrationManifestV1 }[] = [];
+  for (const source of sources) {
+    const path = join(source.skillDir, source.skillId, 'INTEGRATIONS.json');
+    if (!existsSync(path)) continue;
+    try {
+      manifests.push({ path, value: parseHarnessIntegrationManifestJson(readFileSync(path, 'utf8')) });
+    } catch (error) {
+      throw new IntegrationManifestError(path, error instanceof Error ? error.message : String(error));
+    }
+  }
+  if (manifests.length === 0) return { manifest: undefined, digest: undefined, sourcePaths: [] };
+
+  const mcp = Object.create(null) as Record<string, NonNullable<HarnessIntegrationManifestV1['mcpServers']>[string]>;
+  const hooks = new Map<string, NonNullable<HarnessIntegrationManifestV1['hooks']>[number]>();
+  for (const source of manifests) {
+    for (const [id, intent] of Object.entries(source.value.mcpServers ?? {})) {
+      const previous = mcp[id];
+      if (previous !== undefined && canonicalIntegrationJson(previous) !== canonicalIntegrationJson(intent)) {
+        throw new IntegrationManifestError(source.path, `conflicting MCP registration id ${JSON.stringify(id)}`);
+      }
+      mcp[id] = intent;
+    }
+    for (const hook of source.value.hooks ?? []) {
+      const previous = hooks.get(hook.id);
+      if (previous !== undefined && canonicalIntegrationJson(previous) !== canonicalIntegrationJson(hook)) {
+        throw new IntegrationManifestError(source.path, `conflicting hook registration id ${JSON.stringify(hook.id)}`);
+      }
+      hooks.set(hook.id, hook);
+    }
+  }
+  const aggregate = {
+    version: 1 as const,
+    ...(Object.keys(mcp).length > 0 ? { mcpServers: Object.fromEntries(Object.entries(mcp).sort(([a], [b]) => a.localeCompare(b))) } : {}),
+    ...(hooks.size > 0 ? { hooks: [...hooks.values()].sort((a, b) => a.id.localeCompare(b.id)) } : {}),
+  } satisfies HarnessIntegrationManifestV1;
+  const count = Object.keys(aggregate.mcpServers ?? {}).length + (aggregate.hooks?.length ?? 0);
+  if (count > INTEGRATION_REGISTRATION_MAX_COUNT) {
+    throw new IntegrationManifestError('<aggregate>', `final aggregate has ${count} registrations; maximum is ${INTEGRATION_REGISTRATION_MAX_COUNT}`);
+  }
+  const aggregateBytes = Buffer.byteLength(canonicalIntegrationJson(aggregate), 'utf8');
+  if (aggregateBytes > INTEGRATION_MANIFEST_MAX_BYTES) {
+    throw new IntegrationManifestError('<aggregate>', `final aggregate exceeds ${INTEGRATION_MANIFEST_MAX_BYTES} UTF-8 bytes`);
+  }
+  return {
+    manifest: aggregate,
+    digest: integrationManifestDigest([aggregate]),
+    sourcePaths: manifests.map((source) => source.path),
+  };
+}
+
+export function notRequestedOutcomes(target: TargetName): readonly [IntegrationOutcome, IntegrationOutcome] {
+  return [
+    { target, component: 'mcp', status: 'not-requested', registrations: [] },
+    { target, component: 'hooks', status: 'not-requested', registrations: [] },
+  ];
+}
+
+export function refusedOutcome(
+  target: TargetName,
+  component: IntegrationComponent,
+  reasonCode: IntegrationReasonCode,
+  remediation: string,
+): IntegrationOutcome {
+  return { target, component, status: 'refused', registrations: [], reasonCode, remediation };
+}
+
+/** Static synchronous outcomes for Gemini/agents-md and other refusal-only seams. */
+export function staticPolicyOutcomes(
+  target: TargetName,
+  manifest: HarnessIntegrationManifestV1 | undefined,
+  noHooks = false,
+): readonly [IntegrationOutcome, IntegrationOutcome] {
+  if (manifest === undefined) return notRequestedOutcomes(target);
+  const mcpRequested = Object.keys(manifest.mcpServers ?? {}).length > 0;
+  const hooksRequested = (manifest.hooks?.length ?? 0) > 0 && !noHooks;
+  const mcpCell = TARGET_INTEGRATION_POLICY[target].mcp;
+  const hookCell = TARGET_INTEGRATION_POLICY[target].hooks;
+  return [
+    mcpRequested
+      ? refusedOutcome(target, 'mcp', mcpCell.reasonCode ?? 'NO_QUALIFYING_LIVE_RECEIPT', 'run dz integrations-verify for an exact-version receipt')
+      : { target, component: 'mcp', status: 'not-requested', registrations: [] },
+    hooksRequested
+      ? refusedOutcome(target, 'hooks', hookCell.reasonCode ?? 'NO_ACTIVATION_RECEIPT', 'run dz integrations-verify with a hook canary and negative control')
+      : { target, component: 'hooks', status: 'not-requested', registrations: [] },
+  ];
+}

package/src/vector-tier.ts

@@ -56,6 +56,7 @@ import {
   updateReinforcementState,
   type PatternRecord,
   type RecallHit,
+  type RecallPatternsOptions,
 } from './patterns.js';
 import {
   indexPatternsToAgentdb,
@@ -202,6 +203,8 @@ export interface HybridHit {
   readonly score: number;
   /** lesson-quarantine: set only for a quarantined hit — display marks ⚠q, ranking was damped. */
   readonly quarantined?: boolean;
+  /** Form provenance from the lexical pair merge; semantic ranking never invents it. */
+  readonly matchedForm?: NonNullable<RecallHit['matchedForm']>;
   /**
    * Raw closeness from the semantic leg, when the engine reports a genuine cosine. ABSENT for a
    * lexical-only hit and for an engine whose score is not a cosine — the honest display there is a
@@ -491,7 +494,7 @@ export function isVectorNoise(text: string): boolean {
  * ingest gate — I-6). Score is the record's REAL reward, never a fabricated 1.0.
  */
 export function patternVectorEntry(p: PatternRecord, source = 'dz-teach', opts: { quarantined?: boolean } = {}): VectorEntry | undefined {
-  if (isVectorNoise(p.pattern)) return undefined;
+  if (p.lessonForm === 'class' || isVectorNoise(p.pattern)) return undefined;
   const dzId = patternRecordId(p);
   return {
     dzId,
@@ -501,7 +504,13 @@ export function patternVectorEntry(p: PatternRecord, source = 'dz-teach', opts:
     tags: ['dz-teach', p.type],
     // FR-8: quarantine rides into the mirror so the HOOK DAEMON (which reads only the mirror's
     // sqlite metadata) can exclude unproven lessons from auto-injection.
-    metadata: { dzId, source, ts: p.ts, domain: p.domain, ...(opts.quarantined === true ? { qStatus: 'quarantined' } : {}) },
+    metadata: {
+      dzId, source, ts: p.ts, domain: p.domain,
+      ...(p.lessonForm !== undefined && p.lessonPairId !== undefined
+        ? { lessonForm: p.lessonForm, lessonPairId: p.lessonPairId }
+        : {}),
+      ...(opts.quarantined === true ? { qStatus: 'quarantined' } : {}),
+    },
   };
 }
 
@@ -525,7 +534,7 @@ export function dreamVectorEntry(d: DreamPattern): VectorEntry | undefined {
 
 /** ACL: stored {@link MemoryRecord} → {@link VectorEntry} (the consolidate-backfill mapper). */
 export function memoryRecordVectorEntry(r: MemoryRecord): VectorEntry | undefined {
-  if (isVectorNoise(r.text)) return undefined;
+  if (r.metadata?.['lessonForm'] === 'class' || isVectorNoise(r.text)) return undefined;
   const state = readReinforcementState(r);
   return {
     dzId: r.id,
@@ -533,7 +542,12 @@ export function memoryRecordVectorEntry(r: MemoryRecord): VectorEntry | undefine
     score: r.score,
     taskType: r.id.startsWith('dream:') ? 'dz-learning' : 'dz-teach',
     tags: ['dz-backfill', r.outcome],
-    metadata: { dzId: r.id, source: r.metadata?.['source'] ?? 'dz-backfill', ts: r.timestamp, skillId: r.skillId },
+    metadata: {
+      dzId: r.id, source: r.metadata?.['source'] ?? 'dz-backfill', ts: r.timestamp, skillId: r.skillId,
+      ...(r.metadata?.['lessonForm'] === 'specific' && typeof r.metadata?.['lessonPairId'] === 'string'
+        ? { lessonForm: 'specific', lessonPairId: r.metadata['lessonPairId'] }
+        : {}),
+    },
     uses: state.uses,
     avgReward: state.avgReward,
   };
@@ -939,6 +953,7 @@ export interface RankedPattern {
   readonly id: string;
   readonly pattern: PatternRecord;
   readonly backend: RecallHit['backend'];
+  readonly matchedForm?: NonNullable<RecallHit['matchedForm']>;
   /**
    * The semantic leg's raw closeness, when the engine reports a real cosine. Rides ALONGSIDE the RRF
    * score and never enters the ranking maths — four things depend on RRF magnitude (the reinforce
@@ -967,11 +982,12 @@ export function mergeHybridHits(
   opts: { readonly limit: number; readonly semanticWeight?: number | undefined },
 ): HybridHit[] {
   const weight = opts.semanticWeight ?? 1;
-  interface Acc { pattern: PatternRecord; lex?: RecallHit['backend']; sem: boolean; score: number; similarity?: number }
+  interface Acc { pattern: PatternRecord; lex?: RecallHit['backend']; sem: boolean; score: number; similarity?: number; matchedForm?: NonNullable<RecallHit['matchedForm']> }
   const acc = new Map<string, Acc>();
   lexical.forEach((h, rank) => {
     const cur = acc.get(h.id) ?? { pattern: h.pattern, sem: false, score: 0 };
     cur.lex = h.backend;
+    if (h.matchedForm !== undefined) cur.matchedForm = h.matchedForm;
     cur.score += 1 / (RRF_K + rank + 1);
     acc.set(h.id, cur);
   });
@@ -997,6 +1013,7 @@ export function mergeHybridHits(
     pattern: v.pattern,
     backend: v.lex !== undefined && v.sem ? ('both' as const) : v.lex ?? ('vector' as const),
     score: v.score,
+    ...(v.matchedForm === undefined ? {} : { matchedForm: v.matchedForm }),
     ...(v.similarity === undefined ? {} : { similarity: v.similarity }),
   });
   // `slice(0, -1)` drops the LAST element instead of returning nothing, so a negative limit used to
@@ -1105,6 +1122,8 @@ export async function recallHybrid(
      * sitting at `pulls === 0` forever. Absent ⇒ `general`; it changes nothing while disarmed.
      */
     readonly domain?: string | undefined;
+    readonly onClassDegraded?: RecallPatternsOptions['onClassDegraded'];
+    readonly classMatcher?: RecallPatternsOptions['classMatcher'];
   } = {},
 ): Promise<HybridRecall> {
   // Config-surface note (QE P3, benign by design): recall resolves the engine directly, while teach
@@ -1116,7 +1135,10 @@ export async function recallHybrid(
   // write-side backend flag.
   const limit = opts.limit ?? 10;
   const mode = opts.mode ?? 'hybrid';
-  const lexical = recallPatterns(projectRoot, query, limit);
+  const lexical = recallPatterns(projectRoot, query, limit, {
+    ...(opts.onClassDegraded === undefined ? {} : { onClassDegraded: opts.onClassDegraded }),
+    ...(opts.classMatcher === undefined ? {} : { classMatcher: opts.classMatcher }),
+  });
   const lexicalBackend: 'sqlite' | 'json' = lexical[0]?.backend === 'sqlite' ? 'sqlite' : 'json';
   const records = loadStoreRecords(projectRoot);
   const idToRecord = new Map<string, MemoryRecord>();
@@ -1223,7 +1245,12 @@ export async function recallHybrid(
         };
   const lexicalOnly = (extra: Partial<Pick<HybridRecall, 'vectorEngine' | 'vectorReason' | 'vectorError'>>): HybridRecall => {
     // `enhance` FIRST: it is what populates `banditReport` (the key is absent while disarmed).
-    const hits = enhance(lexical.map((h, rank) => ({ pattern: h.pattern, backend: h.backend, score: 1 / (RRF_K + rank + 1) })));
+    const hits = enhance(lexical.map((h, rank) => ({
+      pattern: h.pattern,
+      backend: h.backend,
+      score: 1 / (RRF_K + rank + 1),
+      ...(h.matchedForm === undefined ? {} : { matchedForm: h.matchedForm }),
+    })));
     return {
       hits,
       lexicalBackend,
@@ -1333,6 +1360,7 @@ export async function recallHybrid(
     id: identityToId.get(patternIdentityOf(h.pattern)) ?? patternRecordId(h.pattern),
     pattern: h.pattern,
     backend: h.backend,
+    ...(h.matchedForm === undefined ? {} : { matchedForm: h.matchedForm }),
   }));
   const hits = enhance(mergeHybridHits(lex, semantic, { limit, semanticWeight: mode === 'semantic' ? 2 : 1 }));
   markRecallHits(projectRoot, learning, hits, idOf, banditEmission());
@@ -1688,13 +1716,15 @@ export async function harmonizeVectorStore(projectRoot: string, opts: HarmonizeO
   } catch {
     records = [];
   }
-  const items: HarmonizeItem[] = records.map((r) => ({
-    dzId: r.id,
-    text: r.text,
-    reward: r.score,
-    ts: r.timestamp,
-    taskType: r.id.startsWith('dream:') ? 'dz-learning' : 'dz-teach',
-  }));
+  const items: HarmonizeItem[] = records
+    .filter((r) => r.metadata?.['lessonForm'] !== 'class')
+    .map((r) => ({
+      dzId: r.id,
+      text: r.text,
+      reward: r.score,
+      ts: r.timestamp,
+      taskType: r.id.startsWith('dream:') ? 'dz-learning' : 'dz-teach',
+    }));
 
   // 2. GATE: an embedder ⇒ SEMANTIC clustering; absence/failure ⇒ EXACT-text fallback (D4).
   let embed: ((text: string) => Promise<Float32Array>) | undefined;

package/src/workflow-run.ts

@@ -33,6 +33,7 @@ import {
   traceInit,
   traceLedgerLine,
   traceOnDispatch,
+  traceOnFanoutTruncated,
   traceOnSettle,
   traceShellQuote,
   TRACE_KEY_RE,
@@ -336,7 +337,7 @@ export function computeBoundaryReservations(
     if (b.kind === 'region') {
       const r = b.region;
       if (r === undefined) continue;
-      const members = activatedMembers(r.registry, r.dedup, r.maxFanout).length;
+      const members = activatedMembers(r.registry, r.dedup, r.maxFanout, r.overflow).length;
       const perItem = r.chain.reduce((n, s) => n + worstCaseInvocations(s), 0);
       const perItemWall = r.chain.reduce((n, s) => n + worstCaseInvocations(s) * timeoutMsFor(s), 0);
       out.push({
@@ -366,17 +367,14 @@ export function computeBoundaryReservations(
 /**
  * The members a fanout actually ACTIVATES.
  *
- * `maxFanout` caps ACTIVATION, not merely concurrency — the rendered script emits
- * `registry.slice(0, maxFanout)` ("bounded fanout (INV-2): never args-derived, never uncapped").
- * Getting this wrong is a STRUCTURAL-EQUIVALENCE break, not a performance detail: a runner that
- * treated the bound as a concurrency limit would dispatch all six entries of a six-item registry
- * where the Claude host dispatched three, and the two hosts' traces would disagree on dispatch
- * multiplicity for the same plan. (MEASURED: that is exactly what the F5 equivalence leg caught
- * against the committed `pkg-audit-1` run — 6 lanes here, 3 there.)
+ * `maxFanout` caps CONCURRENCY under the default/window policy. Only the explicitly declared
+ * `overflow:'truncate'` escape hatch caps activation, and that path owes stderr + trace receipts.
+ * This function is shared by reservation arithmetic and enactment so neither can silently retain
+ * the old prefix-only interpretation.
  */
-function activatedMembers(registry: string[], dedup: boolean, maxFanout: number): string[] {
+function activatedMembers(registry: string[], dedup: boolean, maxFanout: number, overflow: 'window' | 'truncate'): string[] {
   const base = dedup ? [...new Set(registry)] : [...registry];
-  return maxFanout > 0 ? base.slice(0, maxFanout) : base;
+  return overflow === 'truncate' && maxFanout > 0 ? base.slice(0, maxFanout) : base;
 }
 
 /**
@@ -1605,7 +1603,16 @@ async function runStage(ctx: RunCtx, b: RunBoundary): Promise<string | null> {
 async function runRegion(ctx: RunCtx, b: RunBoundary): Promise<void> {
   const r = b.region;
   if (r === undefined) return;
-  const members = activatedMembers(r.registry, r.dedup, r.maxFanout);
+  const members = activatedMembers(r.registry, r.dedup, r.maxFanout, r.overflow);
+  if (r.overflow === 'truncate') {
+    traceOnFanoutTruncated(ctx.trace, {
+      stage: r.fanout,
+      registrySize: r.registry.length,
+      dispatched: members.length,
+      reason: r.truncateReason ?? '',
+    });
+    flush(ctx);
+  }
   for (const k of members) {
     if (!safeItemKey(k)) {
       throw new RunFailure(