@dzhechkov/harness-core 0.8.6 → 0.8.10

package/src/guard.ts

@@ -11,8 +11,16 @@
 // PURE: `evaluateGuard` operates over INJECTED FACTS (package.json deps, a drift result, lesson text, README
 // counts, store size) that the CLI gathers. No filesystem here → deterministic + unit-testable without a repo.
 
-import { type RuleTemplate, type TemplateParams, type ChangeSet, templateFires, validTemplateParams } from './guard-promotion.js';
+import { lessonRuleContentAnchor, type RuleTemplate, type TemplateParams, type ChangeSet, templateFires, validTemplateParams } from './guard-promotion.js';
 import { STUB_MARKERS, STUB_PHRASES, checkNoStubs, type StubWaiver } from './no-stubs.js';
+import {
+  VOLUME_SHADOW_RULE_IDS,
+  evaluateVolumeShadow,
+  unknownVolumeShadow,
+  type GuardObservation,
+  type VolumeShadowInput,
+  type VolumeShadowResult,
+} from './guard-volume.js';
 
 export type GuardSeverity = 'hard' | 'soft';
 export type GuardOp = 'publish' | 'teach' | 'consolidate' | 'reindex';
@@ -39,6 +47,8 @@ export interface Violation {
   readonly rule: string;
   readonly severity: GuardSeverity;
   readonly detail: string;
+  /** Present for promoted-template firings; ids alone do not prove equal effective rule content. */
+  readonly contentAnchor?: string;
 }
 
 export interface GuardResult {
@@ -54,11 +64,15 @@ export interface GuardResult {
    * argument; a note is the cheap fix. Present only when non-empty.
    */
   readonly notes?: readonly string[];
+  /** Versioned shadow measurements. They are evidence only and never enter the verdict reducer. */
+  readonly observations?: readonly GuardObservation[];
 }
 
 /** Facts the CLI injects; each rule reads only the fields it needs. Missing evidence ⇒ that rule is skipped. */
 export interface GuardFacts {
   readonly op: GuardOp;
+  /** Publish-only raw volume facts. Absence preserves the legacy result shape. */
+  readonly volume?: VolumeShadowInput;
   /** for no-workspace-star: each publishable package's deps map. */
   readonly packages?: readonly { readonly name: string; readonly deps: Readonly<Record<string, string>> }[];
   /** for no-skill-drift: the names that byte-drift between copies (from sweepSkillDrift). */
@@ -287,6 +301,10 @@ export const DEFAULT_RULES: readonly GuardRule[] = [
   { id: 'readme-first', severity: 'soft', ops: ['publish'], description: 'a package with a staged version bump must update its own README.md in the same change (README-first)' },
   { id: 'routing-store-stale', severity: 'soft', ops: ['publish'], description: 'harvested routing telemetry has been applied to the auto-cost outcome store' },
   { id: 'marketplace-parity', severity: 'soft', ops: ['publish'], description: 'the published .claude-plugin/ showcase composition matches a fresh regeneration from the live registry (version excluded — an operator field)' },
+  { id: 'template-context-token-weight', severity: 'soft', ops: ['publish'], description: 'observe the UTF-8-byte estimated token weight of each selected template context corpus; measured starting points are advisory only' },
+  { id: 'template-context-largest-file-share', severity: 'soft', ops: ['publish'], description: 'observe the largest template file share on the same estimated-token basis as its corpus total; advisory only' },
+  { id: 'feature-artifact-diff-ratio', severity: 'soft', ops: ['publish'], description: 'observe feature artifact bytes against attributable unified-diff bytes, explicitly a proxy; advisory only' },
+  { id: 'feature-tier-artifact-set', severity: 'soft', ops: ['publish'], description: 'observe artifacts due for the recorded feature tier, active steps, consumers, and lifecycle; advisory only' },
   { id: 'agents-md-policy-sync', severity: 'soft', ops: ['publish'], description: 'proves the AGENTS.md copy is in SYNC with its source — not that the runtime read or obeyed it; heal drift with dz agents-sync' },
   { id: 'lockfile-in-sync', severity: 'soft', ops: ['publish'], description: 'every workspace @dzhechkov/* dependency spec matches the specifier pnpm-lock.yaml records for that importer (a dep bump without a lockfile refresh breaks CI with ERR_PNPM_OUTDATED_LOCKFILE). SOFT-ONLY — a config cannot promote it to HARD' },
   { id: 'store-bloat-cap', severity: 'soft', ops: ['teach', 'consolidate'], description: 'the learned store is within its size cap' },
@@ -586,7 +604,13 @@ const CHECKERS: Record<string, (f: GuardFacts, sev: GuardSeverity) => Violation[
  * may not understand a file, and "I might be wrong" plus "block the publish" is the wrong pair. Disabling
  * such a rule stays allowed — only the promotion is refused.
  */
-export const SOFT_ONLY_RULES: readonly string[] = ['lockfile-in-sync', 'agents-md-policy-sync', 'routing-store-stale', 'marketplace-parity'];
+export const SOFT_ONLY_RULES: readonly string[] = [
+  'lockfile-in-sync',
+  'agents-md-policy-sync',
+  'routing-store-stale',
+  'marketplace-parity',
+  ...VOLUME_SHADOW_RULE_IDS,
+];
 
 /**
  * A well-formed PROMOTED rule: an id the engine does not know, made enforceable by a template +
@@ -612,7 +636,12 @@ function templateChecker(rule: GuardRule & { template: RuleTemplate; params: Tem
     const r = templateFires(rule.template, rule.params, change);
     if (Object.hasOwn(r, 'undecidable') || !(r as { fired?: boolean }).fired) return [];
     // A promoted rule is ALWAYS soft, whatever severity reaches this point (belt to resolveRules' braces).
-    return [{ rule: rule.id, severity: 'soft', detail: `${(r as { detail?: string }).detail ?? 'template rule fired'} (promoted rule — advisory)` }];
+    return [{
+      rule: rule.id,
+      severity: 'soft',
+      detail: `${(r as { detail?: string }).detail ?? 'template rule fired'} (promoted rule — advisory)`,
+      contentAnchor: lessonRuleContentAnchor(rule.template, rule.params),
+    }];
   };
 }
 
@@ -671,8 +700,32 @@ export function evaluateGuard(facts: GuardFacts, rules: readonly GuardRule[] = D
   );
   const violations: Violation[] = [];
   const checked: string[] = [];
+  const observations: GuardObservation[] = [];
+  let volumeResult: VolumeShadowResult | undefined;
+  let volumeEvaluated = false;
+  const volume = (): VolumeShadowResult => {
+    if (volumeEvaluated) return volumeResult ?? { observations: [], signals: [], notes: [] };
+    volumeEvaluated = true;
+    try {
+      volumeResult = evaluateVolumeShadow(facts.volume);
+    } catch (error) {
+      volumeResult = unknownVolumeShadow(
+        'volume-evaluator-failure',
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+    return volumeResult;
+  };
   for (const r of active) {
     checked.push(r.id);
+    if ((VOLUME_SHADOW_RULE_IDS as readonly string[]).includes(r.id)) {
+      const emission = volume();
+      observations.push(...emission.observations.filter((item) => item.rule === r.id));
+      violations.push(...emission.signals
+        .filter((signal) => signal.rule === r.id)
+        .map((signal) => ({ rule: signal.rule, severity: 'soft' as const, detail: signal.detail })));
+      continue;
+    }
     // A promoted (template) rule has no built-in checker by design — it is enforceable through the
     // shared `templateFires` predicate instead. Without this branch a promoted rule written into
     // `.dz/guard.json` would be INERT: present in the config, listed as checked, enforcing nothing —
@@ -720,7 +773,17 @@ export function evaluateGuard(facts: GuardFacts, rules: readonly GuardRule[] = D
       notes.push('agents-md-policy-sync: this repository carries a dz:policies fence but its canonical policy sources are unreadable — the advisory rule could not compare, and that gap is on the record, not a silent pass');
     }
   }
-  return { op, verdict, violations, checked, ...(notes.length > 0 ? { notes } : {}) };
+  for (const item of observations) {
+    if (item.status === 'unknown') notes.push(`${item.rule} ${item.scope}: ${item.detail}`);
+  }
+  return {
+    op,
+    verdict,
+    violations,
+    checked,
+    ...(notes.length > 0 ? { notes } : {}),
+    ...(observations.length > 0 ? { observations } : {}),
+  };
 }
 
 /** An append-only audit record. `ts` is injected by the caller (no wall-clock here → deterministic tests). */
@@ -731,6 +794,8 @@ export interface GuardAuditRecord {
   readonly violations: readonly Violation[];
   /** informational notes (FN-7 — e.g. the no-stubs skipped-files note); on the record, never a verdict input. */
   readonly notes?: readonly string[];
+  /** Shadow measurements copied without recomputation from the evaluated result. */
+  readonly observations?: readonly GuardObservation[];
   /** set when the operator overrode a block with `--force <reason>` — the override is logged, never silent. */
   readonly override?: { readonly forced: true; readonly reason: string };
 }
@@ -743,6 +808,7 @@ export function auditRecord(result: GuardResult, ts: string, override?: { reason
     verdict: result.verdict,
     violations: result.violations,
     ...(Array.isArray(result.notes) && result.notes.length > 0 ? { notes: result.notes } : {}),
+    ...(Array.isArray(result.observations) && result.observations.length > 0 ? { observations: result.observations } : {}),
     ...(override && typeof override.reason === 'string' ? { override: { forced: true, reason: override.reason } } : {}),
   };
 }

package/src/index.ts

@@ -15,6 +15,11 @@ export * from './apply.js';
 export { bundleSkills } from './bundle.js';
 export type { BundleOptions, BundleResult, BundledSkill } from './bundle.js';
 export * from './targets.js';
+export * from './target-integrations.js';
+export * from './integration-evidence.js';
+export * from './integration-apply.js';
+export * from './integrations-verify.js';
+export { redactProbeText, PROBE_REDACTION_MARKER } from './integration-probe-worker.js';
 // Target-parity model (feature target-parity-matrix, ADR-001) — the computed feature×target map.
 export {
   RUNTIME_CAPABILITIES,
@@ -94,7 +99,8 @@ export { buildRegistry, searchRegistry, filterByCategory, skillPackBaseDirs, dis
 export * from './package-skill-layouts.js';
 export { recommend } from './recommend.js';
 export { pretrain } from './pretrain.js';
-export { loadPatterns, loadSessions, computePatternBoost, readLearningConfig, readMemoryLearningConfig, BOOST_CAP, recordPattern, loadStorePatternsSync, loadStoreRecords, patternToRecord, recordToPattern, patternRecordId, patternIdentityOf, dreamRecordId, isMirrorableLearning, consolidateSessions, recallPatterns, pruneNoisePatterns, removePatternsByIds, snapshotStore, readReinforcementState, encodeReinforcementState, reinforcePattern, updateReinforcementState, storeStats, lessonDeltaReport, lessonDeltaMap, readQuarantineState, encodeQuarantineState, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns } from './patterns.js';
+export { loadPatterns, loadSessions, computePatternBoost, readLearningConfig, readMemoryLearningConfig, BOOST_CAP, recordPattern, recordLessonForms, loadStorePatternsSync, loadStoreRecords, patternToRecord, recordToPattern, patternRecordId, patternIdentityOf, dreamRecordId, isMirrorableLearning, consolidateSessions, recallPatterns, pruneNoisePatterns, removePatternsByIds, snapshotStore, readReinforcementState, encodeReinforcementState, reinforcePattern, updateReinforcementState, storeStats, lessonDeltaReport, lessonDeltaMap, readQuarantineState, encodeQuarantineState, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns } from './patterns.js';
+export { normalizeLessonForms, validateClassTemplate, lessonPairIdOf, mergeLessonFormHits, mergeLessonMatchedForms } from './lesson-generalization.js';
 export { withStoreLock, withStoreLockSync, storeLockPath, StoreLockTimeoutError, StoreLockCompromisedError, STALE_LOCK_MS, LOCK_TIMEOUT_MS } from './store-lock.js';
 export type { StoreLockOptions } from './store-lock.js';
 export { withNamedLockSync, namedLockPath, isSafeLockName, NamedLockNameError, NamedLockTimeoutError, NamedLockCompromisedError } from './named-lock.js';
@@ -121,7 +127,8 @@ export {
   renderBridgeReport,
 } from './qe-bridge.js';
 export type { BridgeFamily, BridgeFailureReason, BridgeFinding, BridgeSignoff, BridgeParse, BridgeParseOk, BridgeParseFail, BridgeChannels, BridgeAudit, ClaudeResultExtraction, NamedExtract, BridgePromptInput } from './qe-bridge.js';
-export type { PatternRecord, SessionRecord, LearningConfig, MemoryLearningConfig, LoadOptions, ConsolidateResult, ConsolidateOptions, SqliteBackendMode, RecallHit, SessionsSource, PruneNoiseResult, RemovePatternsResult, SnapshotStoreResult, ReinforcementState, ReinforcePatternResult, StoreStats, LessonDeltaReport, LessonDeltaRow, QuarantineState, PromoteResult, QuarantineExpiryCandidate } from './patterns.js';
+export type { PatternRecord, SessionRecord, LearningConfig, MemoryLearningConfig, LoadOptions, ConsolidateResult, ConsolidateOptions, SqliteBackendMode, RecallHit, RecallPatternsOptions, RecordLessonFormsResult, SessionsSource, PruneNoiseResult, RemovePatternsResult, SnapshotStoreResult, ReinforcementState, ReinforcePatternResult, StoreStats, LessonDeltaReport, LessonDeltaRow, QuarantineState, PromoteResult, QuarantineExpiryCandidate } from './patterns.js';
+export type { LessonForm, LessonMatchedForm, LessonFormsInput, LessonFormRankedHit, MergedLessonFormHit } from './lesson-generalization.js';
 export { DEFAULT_REINFORCE_THRESHOLD, NoopLearningBackend, NativeReinforcementBackend, resolveLearningBackend, isLearningSignalBackend, applyLearningSignals, applyLearningSignalsWithDelta, applyLearningSignalsWithTerms } from './learning-backend.js';
 export type { LearningSignalBackend, LearningSignalStats, LearningSample, SignalCandidate, EnhanceContext, TrainingResult, LearningBackendMode, RerankTerm } from './learning-backend.js';
 // lesson-bandit-rerank (I-8): the ACL's public surface only. The vendored engine class is
@@ -186,6 +193,15 @@ export { runSetup, generateHooksConfig, generateAgentdbWriter, writerVersionOf,
   agentdbStorePath, agentdbMcpStorePath, agentdbStoreSeparationProblem } from './setup.js';
 export { statuslineData, readFeatureAdrState, writeFeatureAdrState, featureAdrStateDir, featureAdrStatePath } from './statusline.js';
 export type { StatuslineData, FeatureAdrState, WriteFeatureAdrStateInput } from './statusline.js';
+export {
+  ETA_MAX_STAGE_MS,
+  estimateEta,
+  extractStageSamples,
+  formatEta,
+  parseCheckpointLines,
+  segmentRun,
+} from './eta.js';
+export type { CheckpointObservation, EtaEstimate, EtaInput, IncompleteCoverageSample, RunSegment, StageDurationSample, StageSample } from './eta.js';
 export { indexPatternsToAgentdb, resolveAgentdbPath, searchAgentdbPatterns, listAgentdbDzIds, resolveAgentdbEmbedder, cosineSimilarity, importVectorsToAgentdb, reindexAgentdbRows, bumpAgentdbUses, clearAgentdbQuarantine, deleteAgentdbByDzIds, readAgentdbRowsByTaskType, DZ_OWNED_TASK_TYPES } from './agentdb-index.js';
 export type { AgentdbSearchHit, AgentdbSearchResult, AgentdbImportRow } from './agentdb-index.js';
 export { DEFAULT_EMBED_MODEL, LEGACY_EMBED_MODEL, DEFAULT_EMBED_DIM, KNOWN_EMBED_DIMS, resolveEmbedModel, readEmbedManifest, writeEmbedManifest, embedManifestPath, legacyEmbedManifest } from './embedding-config.js';
@@ -250,6 +266,50 @@ export { hookDecision, isFenced, isNewLine, ESCAPE_TEACHING } from './claim-chec
 export type { HookDecision, HookDecisionOpts } from './claim-check-hook-policy.js';
 export { step8ClaimGate } from './feature-adr-claim-gate.js';
 export type { Step8ClaimCounts, Step8ClaimGate } from './feature-adr-claim-gate.js';
+export {
+  DEFAULT_CODE_LANDING_CEILING_MS,
+  CODE_LANDING_CEILING_ENV,
+  decideCodeLandingLiveness,
+  extractCodexCompanionJobId,
+  parseCodeLandingLivenessSignal,
+} from './feature-adr-landing.js';
+export type {
+  CodeLandingLivenessVerdict,
+  CodeLandingLivenessReason,
+  CodeLandingLivenessInput,
+  CodeLandingLivenessDecision,
+  CodeLandingLivenessProbe,
+} from './feature-adr-landing.js';
+export {
+  buildDecisionContext,
+  normalizeDecisionRecall,
+  parseDecisionRecallFrame,
+  parseDecisionRecallApplicationProbe,
+  mergeDecisionRecallEvents,
+  reduceDecisionRecallMetrics,
+  summarizeDecisionRecallReceipts,
+  decisionRecallEnterCmd,
+  decisionRecallRunCmd,
+  decisionRecallAppendCmd,
+  decisionRecallApplicationProbeCmd,
+} from './feature-adr-decision-recall.js';
+export type {
+  DecisionRecallKind,
+  DecisionRecallStage,
+  DecisionRecallOutcomeName,
+  DecisionRecallContext,
+  DecisionRecallFrame,
+  DecisionRecallSelection,
+  DecisionRecallOutcome,
+  DecisionRecallEvent,
+  DecisionRecallDisposition,
+  DecisionRecallApplicationProbe,
+  MergedDecisionRecallAttempt,
+  MergedDecisionRecallDecision,
+  MergedDecisionRecallEvents,
+  DecisionRecallRatio,
+  DecisionRecallMetrics,
+} from './feature-adr-decision-recall.js';
 export {
   CHECKPOINT_STAGES,
   STAGE_ARTIFACTS,
@@ -826,6 +886,7 @@ export * from './model-recommender.js';
 export * from './bto-optimize.js';
 export * from './discrimination-gate.js';
 export * from './guard.js';
+export * from './guard-volume.js';
 // Root AGENTS.md policy projection: pure anchor extraction/render/hash drift +
 // the shared-emitter I/O entry point exported from operations.
 export * from './agents-policy.js';

package/src/integration-apply.ts

@@ -0,0 +1,332 @@
+/** Journaled, ownership-aware project carrier transaction. */
+
+import { createHash, randomBytes } from 'node:crypto';
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+import { canonicalIntegrationJson, parseStrictJson, type CarrierFragment, type IntegrationReasonCode } from '@dzhechkov/core';
+
+import { withNamedLockSync } from './named-lock.js';
+
+const MAX_CARRIER_BYTES = 1024 * 1024;
+const JOURNAL_REL = '.dz/integrations-ownership.json';
+
+type JournalState = 'pending' | 'committed';
+
+interface JournalEntry {
+  readonly state: JournalState;
+  readonly carrierPath: string;
+  readonly entryId: string;
+  readonly previousCarrierDigest: string;
+  readonly desiredCarrierDigest: string;
+  readonly desiredContentHash: string;
+}
+
+interface JournalV1 {
+  readonly version: 1;
+  readonly entries: Record<string, JournalEntry>;
+}
+
+export type IntegrationApplyFault = 'after-pending' | 'after-carrier' | 'after-committed';
+
+export interface ApplyIntegrationOptions {
+  readonly projectRoot: string;
+  readonly fragments: readonly CarrierFragment[];
+  /** Test-only fault seam; production callers omit it. */
+  readonly injectFault?: IntegrationApplyFault;
+}
+
+export interface IntegrationApplyReport {
+  readonly written: readonly string[];
+  readonly alreadyCurrent: readonly string[];
+  readonly journalPath: string;
+}
+
+export class IntegrationApplyError extends Error {
+  constructor(
+    readonly reasonCode: IntegrationReasonCode,
+    message: string,
+    /** Carrier bytes may already be durable while ownership remains unverified. */
+    readonly applied = false,
+  ) {
+    super(message);
+    this.name = 'IntegrationApplyError';
+  }
+}
+
+function sha(value: string | Buffer): string {
+  return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+
+function absentOrDigest(bytes: string | undefined): string {
+  return bytes === undefined ? 'sha256:absent' : sha(bytes);
+}
+
+function assertPlainObject(value: unknown, label: string): Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new IntegrationApplyError('CONFIG_MALFORMED', `${label} must contain a JSON object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function readBoundedJson(path: string, label: string): { bytes: string; value: Record<string, unknown> } | undefined {
+  if (!existsSync(path)) return undefined;
+  const st = lstatSync(path);
+  if (st.isSymbolicLink() || !st.isFile()) throw new IntegrationApplyError('UNSAFE_PATH', `${label} must be a regular non-symlink file`);
+  if (st.size > MAX_CARRIER_BYTES) throw new IntegrationApplyError('CONFIG_MALFORMED', `${label} exceeds ${MAX_CARRIER_BYTES} bytes`);
+  const bytes = readFileSync(path, 'utf8');
+  try {
+    return { bytes, value: assertPlainObject(parseStrictJson(bytes, { label, maxBytes: MAX_CARRIER_BYTES }), label) };
+  } catch (error) {
+    if (error instanceof IntegrationApplyError) throw error;
+    throw new IntegrationApplyError('CONFIG_MALFORMED', error instanceof Error ? error.message : String(error));
+  }
+}
+
+function journalFrom(value: Record<string, unknown>): JournalV1 {
+  if (value['version'] !== 1) throw new IntegrationApplyError('CONFIG_MALFORMED', 'integration journal version must be 1');
+  const rawEntries = assertPlainObject(value['entries'], 'integration journal entries');
+  const entries = Object.create(null) as Record<string, JournalEntry>;
+  for (const [key, raw] of Object.entries(rawEntries)) {
+    const row = assertPlainObject(raw, `integration journal entry ${key}`);
+    const state = row['state'];
+    if (state !== 'pending' && state !== 'committed') throw new IntegrationApplyError('CONFIG_MALFORMED', `integration journal entry ${key} has invalid state`);
+    for (const field of ['carrierPath', 'entryId', 'previousCarrierDigest', 'desiredCarrierDigest', 'desiredContentHash'] as const) {
+      if (typeof row[field] !== 'string') throw new IntegrationApplyError('CONFIG_MALFORMED', `integration journal entry ${key} lacks ${field}`);
+    }
+    entries[key] = {
+      state,
+      carrierPath: row['carrierPath'] as string,
+      entryId: row['entryId'] as string,
+      previousCarrierDigest: row['previousCarrierDigest'] as string,
+      desiredCarrierDigest: row['desiredCarrierDigest'] as string,
+      desiredContentHash: row['desiredContentHash'] as string,
+    };
+  }
+  return { version: 1, entries };
+}
+
+function ensureSafeProjectRoot(projectRoot: string): string {
+  mkdirSync(projectRoot, { recursive: true });
+  const lexical = resolve(projectRoot);
+  const actual = realpathSync(projectRoot);
+  if (lexical !== actual || lstatSync(projectRoot).isSymbolicLink()) {
+    throw new IntegrationApplyError('UNSAFE_PATH', 'project root must be a real non-symlink directory');
+  }
+  const dz = join(actual, '.dz');
+  if (!existsSync(dz)) mkdirSync(dz, { mode: 0o700 });
+  const dzStat = lstatSync(dz);
+  if (dzStat.isSymbolicLink() || !dzStat.isDirectory() || realpathSync(dz) !== dz) {
+    throw new IntegrationApplyError('UNSAFE_PATH', '.dz must be a real non-symlink directory');
+  }
+  return actual;
+}
+
+function confinedPath(root: string, relativePath: string): string {
+  if (relativePath.startsWith('/') || relativePath.split('/').includes('..')) {
+    throw new IntegrationApplyError('UNSAFE_PATH', `unsafe carrier path ${JSON.stringify(relativePath)}`);
+  }
+  const absolute = resolve(root, ...relativePath.split('/'));
+  const rel = relative(root, absolute);
+  if (rel === '..' || rel.startsWith(`..${sep}`) || resolve(root, rel) !== absolute) {
+    throw new IntegrationApplyError('UNSAFE_PATH', `carrier escapes project root: ${relativePath}`);
+  }
+  const parent = dirname(absolute);
+  if (parent !== root) {
+    mkdirSync(parent, { recursive: true });
+    let walk = root;
+    for (const part of relative(root, parent).split(sep).filter(Boolean)) {
+      walk = join(walk, part);
+      const st = lstatSync(walk);
+      if (st.isSymbolicLink() || !st.isDirectory()) throw new IntegrationApplyError('UNSAFE_PATH', `carrier parent is not a real directory: ${relativePath}`);
+    }
+  }
+  if (existsSync(absolute) && lstatSync(absolute).isSymbolicLink()) {
+    throw new IntegrationApplyError('UNSAFE_PATH', `carrier must not be a symlink: ${relativePath}`);
+  }
+  return absolute;
+}
+
+function fsyncDirectory(path: string): void {
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, constants.O_RDONLY);
+    fsyncSync(fd);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (!['EINVAL', 'ENOTSUP', 'EISDIR', 'EPERM'].includes(code ?? '')) throw error;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+function durableReplace(path: string, bytes: string): void {
+  const parent = dirname(path);
+  const temp = join(parent, `.${relative(parent, path)}.dz-${process.pid}-${randomBytes(8).toString('hex')}.tmp`);
+  let fd: number | undefined;
+  try {
+    const noFollow = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
+    fd = openSync(temp, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | noFollow, 0o600);
+    writeFileSync(fd, bytes, 'utf8');
+    fsyncSync(fd);
+    closeSync(fd); fd = undefined;
+    renameSync(temp, path);
+    const reread = readFileSync(path, 'utf8');
+    if (reread !== bytes) throw new IntegrationApplyError('APPLY_FAILED', `durable reread mismatch for ${path}`);
+    fsyncDirectory(parent);
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+    if (existsSync(temp)) unlinkSync(temp);
+  }
+}
+
+function entryHash(value: unknown): string {
+  return sha(canonicalIntegrationJson(value));
+}
+
+function isKnownAgentDbLegacy(id: string, value: unknown, root: string): boolean {
+  if (id !== 'mcpServers.agentdb' || value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const row = value as Record<string, unknown>;
+  if (!Object.keys(row).every((key) => ['command', 'args', 'env'].includes(key))) return false;
+  if (row['command'] !== 'npx' || !Array.isArray(row['args'])) return false;
+  const args = row['args'];
+  if (args.length !== 3 || typeof args[0] !== 'string' || !/^agentdb@(?:latest|[^\s/]+)$/.test(args[0]) || args[1] !== 'mcp' || args[2] !== 'start') return false;
+  if (row['env'] === undefined) return true;
+  const env = row['env'];
+  if (env === null || typeof env !== 'object' || Array.isArray(env) || Object.keys(env).length !== 1) return false;
+  const path = (env as Record<string, unknown>)['AGENTDB_PATH'];
+  return path === join(root, '.dz', 'agentdb.db') || path === join(root, '.dz', 'agentdb-mcp.db');
+}
+
+/** Apply all project JSON fragments under one short project-journal lock. */
+export function applyIntegrationFragments(options: ApplyIntegrationOptions): IntegrationApplyReport {
+  const root = ensureSafeProjectRoot(options.projectRoot);
+  const journalPath = confinedPath(root, JOURNAL_REL);
+  if (options.fragments.some((fragment) => fragment.scope !== 'project' || fragment.format !== 'json')) {
+    throw new IntegrationApplyError('INTENT_NOT_EXPRESSIBLE', 'initial transaction supports project JSON carriers only');
+  }
+  const groups = new Map<string, CarrierFragment[]>();
+  for (const fragment of options.fragments) {
+    const rows = groups.get(fragment.carrierPath) ?? [];
+    rows.push(fragment); groups.set(fragment.carrierPath, rows);
+  }
+  if (groups.size === 0) return { written: [], alreadyCurrent: [], journalPath: JOURNAL_REL };
+
+  return withNamedLockSync(root, 'integrations', () => {
+    const rootBefore = statSync(root);
+    const dzBefore = statSync(join(root, '.dz'));
+    const journalRead = readBoundedJson(journalPath, JOURNAL_REL);
+    const journal: JournalV1 = journalRead === undefined ? { version: 1, entries: Object.create(null) } : journalFrom(journalRead.value);
+    const candidates: { rel: string; abs: string; before: string | undefined; bytes: string; tuples: string[] }[] = [];
+    const pendingEntries: Record<string, JournalEntry> = { ...journal.entries };
+
+    for (const [carrierRel, fragments] of [...groups.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+      const carrierAbs = confinedPath(root, carrierRel);
+      const existing = readBoundedJson(carrierAbs, carrierRel);
+      const rootObject = existing?.value ?? Object.create(null) as Record<string, unknown>;
+      const candidate = { ...rootObject } as Record<string, unknown>;
+      const tuples: string[] = [];
+      for (const fragment of fragments) {
+        const rootValue = candidate[fragment.rootKey];
+        const bucket = rootValue === undefined ? Object.create(null) as Record<string, unknown> : assertPlainObject(rootValue, `${carrierRel}.${fragment.rootKey}`);
+        const nextBucket = { ...bucket };
+        for (const [id, desired] of Object.entries(fragment.entries)) {
+          const tuple = `${carrierRel}::${fragment.rootKey}.${id}`;
+          const current = bucket[id];
+          const ledger = journal.entries[tuple];
+          const desiredHash = entryHash(desired);
+          if (current !== undefined) {
+            const currentHash = entryHash(current);
+            const recoverablePending = ledger?.state === 'pending' &&
+              currentHash === ledger.desiredContentHash &&
+              desiredHash === ledger.desiredContentHash;
+            const committedCurrent = ledger?.state === 'committed' && currentHash === ledger.desiredContentHash;
+            const legacy = isKnownAgentDbLegacy(`${fragment.rootKey}.${id}`, current, root);
+            if (!recoverablePending && !committedCurrent && !legacy) {
+              throw new IntegrationApplyError('OWNERSHIP_AMBIGUOUS', `${tuple} already exists without matching dz ownership; original bytes preserved`);
+            }
+          } else if (ledger?.state === 'pending') {
+            // Explicitly recoverable: pending publication may have stopped before carrier rename.
+          } else if (ledger?.state === 'committed') {
+            throw new IntegrationApplyError('OWNERSHIP_AMBIGUOUS', `${tuple} is absent but journal is committed; refuse implicit recreation`);
+          }
+          nextBucket[id] = desired;
+          tuples.push(tuple);
+          pendingEntries[tuple] = {
+            state: 'pending',
+            carrierPath: carrierRel,
+            entryId: `${fragment.rootKey}.${id}`,
+            previousCarrierDigest: absentOrDigest(existing?.bytes),
+            desiredCarrierDigest: '',
+            desiredContentHash: desiredHash,
+          };
+        }
+        candidate[fragment.rootKey] = nextBucket;
+      }
+      const bytes = `${JSON.stringify(candidate, null, 2)}\n`;
+      const desiredCarrierDigest = sha(bytes);
+      for (const tuple of tuples) pendingEntries[tuple] = { ...pendingEntries[tuple]!, desiredCarrierDigest };
+      candidates.push({ rel: carrierRel, abs: carrierAbs, before: existing?.bytes, bytes, tuples });
+    }
+
+    if (statSync(root).dev !== rootBefore.dev || statSync(root).ino !== rootBefore.ino ||
+        statSync(join(root, '.dz')).dev !== dzBefore.dev || statSync(join(root, '.dz')).ino !== dzBefore.ino) {
+      throw new IntegrationApplyError('CONCURRENT_MODIFICATION', 'project root or .dz inode changed during planning');
+    }
+
+    const pendingBytes = `${JSON.stringify({ version: 1, entries: pendingEntries }, null, 2)}\n`;
+    durableReplace(journalPath, pendingBytes);
+    if (options.injectFault === 'after-pending') throw new IntegrationApplyError('APPLY_FAILED', 'injected fault after pending journal publication');
+
+    const written: string[] = [];
+    const alreadyCurrent: string[] = [];
+    let carrierPublished = false;
+    try {
+      for (const candidate of candidates) {
+        const current = readBoundedJson(candidate.abs, candidate.rel)?.bytes;
+        if (current !== candidate.before) throw new IntegrationApplyError('CONCURRENT_MODIFICATION', `${candidate.rel} changed after planning`);
+        if (current === candidate.bytes) alreadyCurrent.push(candidate.rel);
+        else {
+          durableReplace(candidate.abs, candidate.bytes);
+          written.push(candidate.rel);
+          carrierPublished = true;
+        }
+      }
+      if (options.injectFault === 'after-carrier') {
+        throw new IntegrationApplyError('APPLY_FAILED', 'carrier was written but committed ownership journal was not verified', true);
+      }
+
+      const committedEntries: Record<string, JournalEntry> = { ...pendingEntries };
+      for (const candidate of candidates) {
+        for (const tuple of candidate.tuples) committedEntries[tuple] = { ...committedEntries[tuple]!, state: 'committed' };
+      }
+      durableReplace(journalPath, `${JSON.stringify({ version: 1, entries: committedEntries }, null, 2)}\n`);
+      if (options.injectFault === 'after-committed') throw new IntegrationApplyError('APPLY_FAILED', 'injected fault after committed journal publication', true);
+      return { written, alreadyCurrent, journalPath: JOURNAL_REL };
+    } catch (error) {
+      if (error instanceof IntegrationApplyError && error.applied) throw error;
+      if (carrierPublished) {
+        throw new IntegrationApplyError(
+          'APPLY_FAILED',
+          `carrier was written but committed ownership journal was not verified: ${error instanceof Error ? error.message : String(error)}`,
+          true,
+        );
+      }
+      throw error;
+    }
+  });
+}