my-frontend-observer 0.5.0 → 0.6.0

package/dist/domain/boundedAgentContextCorrelation.d.ts

@@ -0,0 +1,74 @@
+import type { StaticCandidateKind, StaticEvidenceProducerIdentity, RuntimeStaticCorrelationRecord, OmissionRecord, TruncationRecord, BoundedAgentContextArtifact } from './boundedAgentContext.js';
+import type { EvidenceReference } from './relationships.js';
+/** One authoritative static candidate as supplied by the caller (e.g. an application-layer adapter that already ran my-dev-kit retrieval). `candidateId`/`kind` are preserved exactly - never re-minted here. */
+export interface StaticCandidateEvidenceInput {
+    candidateId: string;
+    kind: StaticCandidateKind;
+    evidenceRefs: EvidenceReference[];
+}
+/**
+ * One runtime target's correlation input. `required` mirrors the same
+ * required/optional/context classification the rest of the bounded-context
+ * artifact family already uses (see `boundedAgentContextProjection.ts`) -
+ * it drives required-before-optional allocation and CONTRACT-002 adequacy
+ * consequences, but is not itself part of the frozen public
+ * `RuntimeStaticCorrelationRecord` shape.
+ */
+export interface CorrelationTargetInput {
+    runtimeTargetId: string;
+    required: boolean;
+    runtimeEvidenceRefs: EvidenceReference[];
+    /** Authoritative static candidates already selected/ranked by caller criteria. Empty means "correlation attempted, no responsible candidate available" (=> `unavailable`), which is distinct from omitting this target from `targets` entirely (=> not attempted, no record at all). */
+    candidates: StaticCandidateEvidenceInput[];
+    evidenceBasis?: string;
+}
+export interface DeriveRuntimeStaticCorrelationsInput {
+    /** Authoritative static producer/index identity, preserved exactly. Never derived from a local path, worktree, output directory, or timestamp. */
+    staticProducer: StaticEvidenceProducerIdentity;
+    /** Provenance timestamp for every derived record's `provenance.correlatedAt`. Supplied by the caller (pure function - no internal `Date.now()`), matching the existing `generatedAt`-as-input convention in `boundedAgentContextProjection.ts`. */
+    correlatedAt: string;
+    targets: CorrelationTargetInput[];
+}
+export interface DeriveRuntimeStaticCorrelationsOutput {
+    records: RuntimeStaticCorrelationRecord[];
+    omissions: OmissionRecord[];
+    truncations: TruncationRecord[];
+}
+export type DeriveRuntimeStaticCorrelationsResult = ({
+    ok: true;
+} & DeriveRuntimeStaticCorrelationsOutput) | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Derives zero or more bounded `RuntimeStaticCorrelationRecord`s (one per
+ * supplied target) from authoritative runtime + static evidence. Pure,
+ * deterministic, immutable over its inputs, and terminating for arbitrarily
+ * large valid input (bounded by `MAX_CORRELATION_RECORDS`,
+ * `MAX_STATIC_CANDIDATES_PER_TARGET`, `MAX_EVIDENCE_REFS_PER_CORRELATION_FIELD`).
+ *
+ * Does not itself attach the result to a `BoundedAgentContextArtifact` - see
+ * `attachRuntimeStaticCorrelations` for that (separate, explicit step, so
+ * this function stays usable standalone and testable in isolation).
+ */
+export declare function deriveRuntimeStaticCorrelations(input: DeriveRuntimeStaticCorrelationsInput): DeriveRuntimeStaticCorrelationsResult;
+export type AttachRuntimeStaticCorrelationsResult = {
+    ok: true;
+    artifact: BoundedAgentContextArtifact;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Attaches a previously-derived correlation result to an existing
+ * `BoundedAgentContextArtifact`, immutably (returns a new artifact; never
+ * mutates the input). Enforces cross-artifact coherence (every correlation
+ * record's `runtimeTargetId` must reference a target already present in
+ * `artifact.targets`), re-applies the aggregate `MAX_CORRELATION_RECORDS`/
+ * `MAX_OMISSIONS`/`MAX_TRUNCATIONS` caps to the merged collections, and
+ * recomputes `adequacy` per the frozen CONTRACT-002 rule: any known required
+ * correlation loss or required correlation unavailability forces
+ * `inadequate`; optional-only correlation loss may downgrade an otherwise
+ * `adequate` artifact to `partial`, never to `inadequate`.
+ */
+export declare function attachRuntimeStaticCorrelations(artifact: BoundedAgentContextArtifact, correlation: DeriveRuntimeStaticCorrelationsOutput): AttachRuntimeStaticCorrelationsResult;

package/dist/domain/boundedAgentContextCorrelation.js

@@ -0,0 +1,441 @@
+/**
+ * v0.6 Batch 3: runtime/static correlation derivation + attachment/export
+ * against the existing frozen contract in `boundedAgentContext.ts`
+ * (`RuntimeStaticCorrelationRecord`, `StaticCandidateReference`,
+ * `StaticEvidenceProducerIdentity`, `BoundedAgentContextArtifact.correlations`).
+ *
+ * This module does not invent a new correlation schema, does not rename or
+ * redefine any frozen type/constant, and does not bump the package or
+ * `BoundedAgentContextArtifact` schema version. It implements the bounded,
+ * deterministic, pure derivation behavior the frozen contract already
+ * anticipated but never had an implementation for.
+ *
+ * Pure and synchronous: no my-dev-kit invocation, no repository indexing, no
+ * filesystem access, no re-observation, no recomputation of unrelated
+ * artifacts. Consumes only authoritative supplied evidence (runtime target
+ * identity/evidence and externally supplied static candidate evidence +
+ * static producer/index identity). Mutates none of its inputs.
+ *
+ * my-dev-kit product boundary: this module has no dependency on, import of,
+ * or awareness of `@dailephd/my-dev-kit` at runtime. It accepts neutral,
+ * already-retrieved static evidence through `StaticCandidateEvidenceInput`
+ * and `DeriveRuntimeStaticCorrelationsInput.staticProducer` - both plain
+ * data shapes, never a live my-dev-kit client/process. Static
+ * retrieval/indexing remains my-dev-kit's responsibility outside this
+ * package; this module never re-derives it.
+ *
+ * No source-owner/causality/edit-authorization fabrication: `evidenceBasis`
+ * is passed through (bounded/truncated) from caller-supplied text only,
+ * never synthesized from candidate identity, and candidate/record shape
+ * carries no owner/causedBy-style field (the frozen contract already
+ * excludes one - see the doc comment on `RuntimeStaticCorrelationRecord`).
+ */
+import { STATIC_CANDIDATE_KINDS, MAX_STATIC_CANDIDATES_PER_TARGET, MAX_EVIDENCE_REFS_PER_CORRELATION_FIELD, MAX_TEXT_SUMMARY_CHARS, MAX_CORRELATION_RECORDS, MAX_OMISSIONS, MAX_TRUNCATIONS, isValidStaticEvidenceProducerIdentity, isValidStaticCandidateReference, isValidRuntimeStaticCorrelationRecord, isValidOmissionRecord, isValidTruncationRecord, isValidAdequacy, isValidBoundedAgentContextArtifact, } from './boundedAgentContext.js';
+import { isValidEvidenceReference } from './relationships.js';
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function isEvidenceReferenceArray(value) {
+    return Array.isArray(value) && value.every((entry) => isValidEvidenceReference(entry));
+}
+// ---------------------------------------------------------------------------
+// Boundary validation (fail closed on malformed input rather than silently
+// producing a plausible-looking artifact)
+// ---------------------------------------------------------------------------
+function isValidStaticCandidateEvidenceInput(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (!isNonEmptyString(value.candidateId))
+        return false;
+    if (typeof value.kind !== 'string' || !STATIC_CANDIDATE_KINDS.includes(value.kind))
+        return false;
+    if (value.kind === 'file' && !value.candidateId.startsWith('file:'))
+        return false;
+    if (value.kind === 'symbol' && !value.candidateId.startsWith('symbol:'))
+        return false;
+    return isEvidenceReferenceArray(value.evidenceRefs);
+}
+function isValidCorrelationTargetInput(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (!isNonEmptyString(value.runtimeTargetId))
+        return false;
+    if (typeof value.required !== 'boolean')
+        return false;
+    if (!isEvidenceReferenceArray(value.runtimeEvidenceRefs))
+        return false;
+    if (!Array.isArray(value.candidates) || !value.candidates.every(isValidStaticCandidateEvidenceInput))
+        return false;
+    if (value.evidenceBasis !== undefined && typeof value.evidenceBasis !== 'string')
+        return false;
+    return true;
+}
+function validateDeriveInput(input) {
+    if (!isPlainObject(input))
+        return 'input must be an object';
+    if (!isValidStaticEvidenceProducerIdentity(input.staticProducer))
+        return 'staticProducer must be a valid StaticEvidenceProducerIdentity { name, version, indexId }';
+    if (!isNonEmptyString(input.correlatedAt))
+        return 'correlatedAt must be a non-empty string';
+    if (!Array.isArray(input.targets) || !input.targets.every(isValidCorrelationTargetInput)) {
+        return 'targets must be an array of valid correlation target inputs';
+    }
+    const seen = new Set();
+    for (const target of input.targets) {
+        if (seen.has(target.runtimeTargetId))
+            return `duplicate runtimeTargetId in correlation input: ${target.runtimeTargetId}`;
+        seen.add(target.runtimeTargetId);
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Deterministic ordering / bounded-collection helpers (duplicated per the
+// established per-module convention - see `canonicalize` in
+// `boundedAgentContextIdentity.ts` and `capOmissions`/`capTruncations` in
+// `boundedAgentContextProjection.ts` - rather than importing private
+// module-internal helpers cross-file)
+// ---------------------------------------------------------------------------
+function byPathAscending(a, b) {
+    return a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+}
+/** Dedupe by `path` and sort ascending so evidence-ref order never depends on retrieval/input order (order is not semantically significant here). */
+function canonicalEvidenceRefs(refs) {
+    const byPath = new Map();
+    for (const ref of refs)
+        byPath.set(ref.path, ref);
+    return [...byPath.values()].sort(byPathAscending);
+}
+/**
+ * Rescue fix for C-B3-001 (B3-P004): merges two or more supplied candidates
+ * that share the same authoritative `candidateId` into a single surviving
+ * candidate, unioning their `evidenceRefs` (deduped/ordered later by the
+ * existing `canonicalEvidenceRefs` pass in `deriveOneTarget`). Mirrors the
+ * repository's established nested-collection duplicate-identity precedent -
+ * `boundedEvidenceForTarget` in `boundedAgentContextProjection.ts` (itself a
+ * prior "IMP-B-003" rescue for the same class of permutation-dependent
+ * duplicate-identity problem) - rather than the top-level container-key
+ * reject-on-duplicate precedent used for `runtimeTargetId` in
+ * `validateDeriveInput`: a `candidateId` duplicate is a nested per-target
+ * collection entry, not a top-level record-identity key, so silent
+ * structural rejection is not the matching precedent here.
+ *
+ * `candidateId`/`kind` are never rewritten - the frozen contract's exact
+ * candidate identity is preserved verbatim from whichever supplied entry
+ * matched (identical for every duplicate, since `isValidStaticCandidateEvidenceInput`
+ * already forces `kind` to agree with the `candidateId` prefix). Because
+ * `EvidenceReference` carries only a `path` field, the merge is
+ * content-safe and independent of which duplicate the Map last saw - final
+ * output is fully determined by set union, never by input/duplicate order.
+ */
+function canonicalCandidates(candidates) {
+    const byId = new Map();
+    for (const candidate of candidates) {
+        const existing = byId.get(candidate.candidateId);
+        if (existing === undefined) {
+            byId.set(candidate.candidateId, candidate);
+        }
+        else {
+            byId.set(candidate.candidateId, {
+                candidateId: candidate.candidateId,
+                kind: candidate.kind,
+                evidenceRefs: [...existing.evidenceRefs, ...candidate.evidenceRefs],
+            });
+        }
+    }
+    return [...byId.values()];
+}
+/** Aggregate-cap enforcement for the merged `omissions` collection, same policy as `boundedAgentContextProjection.ts#capOmissions`: required-loss records are preserved preferentially and a single truthful summary record replaces whatever had to be dropped. */
+function capOmissions(records, max) {
+    if (records.length <= max)
+        return [...records];
+    const ranked = [...records].sort((a, b) => Number(b.required) - Number(a.required));
+    const kept = ranked.slice(0, max - 1);
+    const dropped = ranked.slice(max - 1);
+    const anyRequired = dropped.some((d) => d.required);
+    const summary = {
+        subject: 'correlation-omissions-summary',
+        reason: 'omitted-by-bound',
+        required: anyRequired,
+        detail: `${dropped.length} additional omission record(s) omitted by the aggregate ${max}-omission cap`,
+    };
+    return [...kept, summary];
+}
+/** Aggregate-cap enforcement for the merged `truncations` collection, same policy as `capOmissions`. */
+function capTruncations(records, max) {
+    if (records.length <= max)
+        return [...records];
+    const ranked = [...records].sort((a, b) => Number(b.required) - Number(a.required));
+    const kept = ranked.slice(0, max - 1);
+    const dropped = ranked.slice(max - 1);
+    const anyRequired = dropped.some((d) => d.required);
+    const summary = {
+        subject: 'correlation-truncations-summary',
+        limit: max,
+        actualCount: records.length,
+        required: anyRequired,
+    };
+    return [...kept, summary];
+}
+function deriveOneTarget(target, staticProducer, correlatedAt, omissions, truncations) {
+    // Rescue fix for C-B3-001: distinct-candidate identity, not raw entry
+    // count, drives ambiguity - merge duplicate candidateIds before ordering
+    // so a duplicate-inflated entry count can never survive into `status`.
+    const distinctCandidateInputs = canonicalCandidates(target.candidates);
+    // Canonical deterministic candidate ordering: sort by candidateId, never
+    // by input/retrieval order, so ambiguity never picks a "first" winner.
+    const orderedCandidates = [...distinctCandidateInputs].sort((a, b) => (a.candidateId < b.candidateId ? -1 : a.candidateId > b.candidateId ? 1 : 0));
+    let boundedCandidateInputs = orderedCandidates;
+    if (orderedCandidates.length > MAX_STATIC_CANDIDATES_PER_TARGET) {
+        boundedCandidateInputs = orderedCandidates.slice(0, MAX_STATIC_CANDIDATES_PER_TARGET);
+        truncations.push({
+            subject: `correlation:${target.runtimeTargetId}.candidates`,
+            limit: MAX_STATIC_CANDIDATES_PER_TARGET,
+            actualCount: orderedCandidates.length,
+            required: target.required,
+        });
+    }
+    const candidates = boundedCandidateInputs.map((candidate) => {
+        const canonicalRefs = canonicalEvidenceRefs(candidate.evidenceRefs);
+        let boundedRefs = canonicalRefs;
+        if (canonicalRefs.length > MAX_EVIDENCE_REFS_PER_CORRELATION_FIELD) {
+            boundedRefs = canonicalRefs.slice(0, MAX_EVIDENCE_REFS_PER_CORRELATION_FIELD);
+            truncations.push({
+                subject: `correlation:${target.runtimeTargetId}.candidate:${candidate.candidateId}.evidenceRefs`,
+                limit: MAX_EVIDENCE_REFS_PER_CORRELATION_FIELD,
+                actualCount: canonicalRefs.length,
+                required: target.required,
+            });
+        }
+        return { candidateId: candidate.candidateId, kind: candidate.kind, evidenceRefs: boundedRefs };
+    });
+    // Status/candidate-count invariant, computed here (never accepted from the
+    // caller as a separate field) so it can never drift from the actual
+    // candidate count the frozen validator enforces.
+    const status = candidates.length === 0 ? 'unavailable' : candidates.length === 1 ? 'correlated' : 'ambiguous';
+    if (status === 'unavailable' && target.required) {
+        omissions.push({
+            subject: `correlation:${target.runtimeTargetId}`,
+            reason: 'unsupported-or-unavailable',
+            required: true,
+            detail: 'required runtime target had no responsible static candidate available for correlation',
+        });
+    }
+    const canonicalRuntimeRefs = canonicalEvidenceRefs(target.runtimeEvidenceRefs);
+    let runtimeEvidenceRefs = canonicalRuntimeRefs;
+    if (canonicalRuntimeRefs.length > MAX_EVIDENCE_REFS_PER_CORRELATION_FIELD) {
+        runtimeEvidenceRefs = canonicalRuntimeRefs.slice(0, MAX_EVIDENCE_REFS_PER_CORRELATION_FIELD);
+        truncations.push({
+            subject: `correlation:${target.runtimeTargetId}.runtimeEvidenceRefs`,
+            limit: MAX_EVIDENCE_REFS_PER_CORRELATION_FIELD,
+            actualCount: canonicalRuntimeRefs.length,
+            required: target.required,
+        });
+    }
+    let evidenceBasis;
+    if (target.evidenceBasis !== undefined) {
+        if (target.evidenceBasis.length > MAX_TEXT_SUMMARY_CHARS) {
+            evidenceBasis = target.evidenceBasis.slice(0, MAX_TEXT_SUMMARY_CHARS);
+            truncations.push({
+                subject: `correlation:${target.runtimeTargetId}.evidenceBasis`,
+                limit: MAX_TEXT_SUMMARY_CHARS,
+                actualCount: target.evidenceBasis.length,
+                required: target.required,
+            });
+        }
+        else {
+            evidenceBasis = target.evidenceBasis;
+        }
+    }
+    const record = {
+        runtimeTargetId: target.runtimeTargetId,
+        runtimeEvidenceRefs,
+        staticProducer,
+        status,
+        candidates,
+        ...(evidenceBasis !== undefined ? { evidenceBasis } : {}),
+        provenance: { correlatedAt },
+    };
+    return record;
+}
+// ---------------------------------------------------------------------------
+// Public derivation entry point
+// ---------------------------------------------------------------------------
+/**
+ * Derives zero or more bounded `RuntimeStaticCorrelationRecord`s (one per
+ * supplied target) from authoritative runtime + static evidence. Pure,
+ * deterministic, immutable over its inputs, and terminating for arbitrarily
+ * large valid input (bounded by `MAX_CORRELATION_RECORDS`,
+ * `MAX_STATIC_CANDIDATES_PER_TARGET`, `MAX_EVIDENCE_REFS_PER_CORRELATION_FIELD`).
+ *
+ * Does not itself attach the result to a `BoundedAgentContextArtifact` - see
+ * `attachRuntimeStaticCorrelations` for that (separate, explicit step, so
+ * this function stays usable standalone and testable in isolation).
+ */
+export function deriveRuntimeStaticCorrelations(input) {
+    const invalidReason = validateDeriveInput(input);
+    if (invalidReason !== undefined)
+        return { ok: false, reason: invalidReason };
+    const omissions = [];
+    const truncations = [];
+    // Canonical deterministic target ordering: sort by runtimeTargetId, never
+    // by input order, so equivalent input sets always produce the same
+    // logical record ordering regardless of how the caller assembled `targets`.
+    const orderedTargets = [...input.targets].sort((a, b) => (a.runtimeTargetId < b.runtimeTargetId ? -1 : a.runtimeTargetId > b.runtimeTargetId ? 1 : 0));
+    const entries = orderedTargets.map((target) => ({
+        record: deriveOneTarget(target, input.staticProducer, input.correlatedAt, omissions, truncations),
+        required: target.required,
+    }));
+    // Required-before-optional allocation at the MAX_CORRELATION_RECORDS
+    // aggregate bound: required entries are kept first, then optional ones,
+    // in each case ordered by runtimeTargetId for determinism. Overflow beyond
+    // the cap becomes an explicit omission rather than a silently-dropped
+    // record; overflow of a *required* entry is a known required loss.
+    const requiredEntries = entries.filter((e) => e.required);
+    const optionalEntries = entries.filter((e) => !e.required);
+    const orderedEntries = [...requiredEntries, ...optionalEntries];
+    const allowedEntries = orderedEntries.slice(0, MAX_CORRELATION_RECORDS);
+    const droppedEntries = orderedEntries.slice(MAX_CORRELATION_RECORDS);
+    for (const dropped of droppedEntries) {
+        omissions.push({
+            subject: `correlation-record:${dropped.record.runtimeTargetId}`,
+            reason: dropped.required ? 'required-evidence-lost-by-bound' : 'omitted-by-bound',
+            required: dropped.required,
+            detail: `dropped by the aggregate ${MAX_CORRELATION_RECORDS}-correlation-record cap`,
+        });
+    }
+    const records = allowedEntries.map((e) => e.record).sort((a, b) => (a.runtimeTargetId < b.runtimeTargetId ? -1 : a.runtimeTargetId > b.runtimeTargetId ? 1 : 0));
+    // Self-check against the frozen structural validator before returning -
+    // fail closed rather than emit a record this module itself would reject.
+    for (const record of records) {
+        const targetId = record.runtimeTargetId;
+        for (const candidate of record.candidates) {
+            if (!isValidStaticCandidateReference(candidate)) {
+                return { ok: false, reason: `internal derivation produced an invalid StaticCandidateReference for target ${targetId}` };
+            }
+        }
+        if (!isValidRuntimeStaticCorrelationRecord(record)) {
+            return { ok: false, reason: `internal derivation produced an invalid RuntimeStaticCorrelationRecord for target ${targetId}` };
+        }
+    }
+    for (const omission of omissions) {
+        if (!isValidOmissionRecord(omission))
+            return { ok: false, reason: 'internal derivation produced an invalid OmissionRecord' };
+    }
+    for (const truncation of truncations) {
+        if (!isValidTruncationRecord(truncation))
+            return { ok: false, reason: 'internal derivation produced an invalid TruncationRecord' };
+    }
+    return { ok: true, records, omissions, truncations };
+}
+// ---------------------------------------------------------------------------
+// Attachment / export boundary (extends the existing
+// BoundedAgentContextArtifact family in place - no new persistence family)
+// ---------------------------------------------------------------------------
+const REQUIRED_CANDIDATE_TRUNCATION_ADEQUACY_REASON = 'static-correlation-ambiguous';
+const REQUIRED_UNAVAILABLE_ADEQUACY_REASON = 'static-evidence-unavailable';
+const REQUIRED_EVIDENCE_TRUNCATION_ADEQUACY_REASON = 'required-source-evidence-truncated';
+const REQUIRED_RECORD_BOUND_LOSS_ADEQUACY_REASON = 'required-evidence-omitted-by-bound';
+function classifyRequiredAdequacyReason(subject, isOmission) {
+    if (subject.startsWith('correlation-record:'))
+        return REQUIRED_RECORD_BOUND_LOSS_ADEQUACY_REASON;
+    if (subject.includes('.candidates'))
+        return REQUIRED_CANDIDATE_TRUNCATION_ADEQUACY_REASON;
+    if (isOmission)
+        return REQUIRED_UNAVAILABLE_ADEQUACY_REASON;
+    return REQUIRED_EVIDENCE_TRUNCATION_ADEQUACY_REASON;
+}
+/**
+ * Attaches a previously-derived correlation result to an existing
+ * `BoundedAgentContextArtifact`, immutably (returns a new artifact; never
+ * mutates the input). Enforces cross-artifact coherence (every correlation
+ * record's `runtimeTargetId` must reference a target already present in
+ * `artifact.targets`), re-applies the aggregate `MAX_CORRELATION_RECORDS`/
+ * `MAX_OMISSIONS`/`MAX_TRUNCATIONS` caps to the merged collections, and
+ * recomputes `adequacy` per the frozen CONTRACT-002 rule: any known required
+ * correlation loss or required correlation unavailability forces
+ * `inadequate`; optional-only correlation loss may downgrade an otherwise
+ * `adequate` artifact to `partial`, never to `inadequate`.
+ */
+export function attachRuntimeStaticCorrelations(artifact, correlation) {
+    const artifactValidation = isValidBoundedAgentContextArtifact(artifact);
+    if (!artifactValidation.valid)
+        return { ok: false, reason: `artifact is invalid: ${artifactValidation.reason}` };
+    if (!Array.isArray(correlation.records) || !correlation.records.every(isValidRuntimeStaticCorrelationRecord)) {
+        return { ok: false, reason: 'correlation.records must be an array of valid runtime/static correlation records' };
+    }
+    if (!Array.isArray(correlation.omissions) || !correlation.omissions.every(isValidOmissionRecord)) {
+        return { ok: false, reason: 'correlation.omissions must be an array of valid omission records' };
+    }
+    if (!Array.isArray(correlation.truncations) || !correlation.truncations.every(isValidTruncationRecord)) {
+        return { ok: false, reason: 'correlation.truncations must be an array of valid truncation records' };
+    }
+    if (artifact.correlations !== undefined && artifact.correlations.length > 0) {
+        return { ok: false, reason: 'artifact already carries correlations; attaching twice is not supported (avoids silent overwrite/merge ambiguity)' };
+    }
+    const knownTargetIds = new Set(artifact.targets.map((t) => t.targetId));
+    for (const record of correlation.records) {
+        if (!knownTargetIds.has(record.runtimeTargetId)) {
+            return { ok: false, reason: `correlation record runtimeTargetId "${record.runtimeTargetId}" does not reference any target in artifact.targets (cross-artifact coherence violation)` };
+        }
+    }
+    const mergedOmissionsRaw = [...artifact.omissions, ...correlation.omissions];
+    const mergedTruncationsRaw = [...artifact.truncations, ...correlation.truncations];
+    const mergedOmissions = capOmissions(mergedOmissionsRaw, MAX_OMISSIONS);
+    const mergedTruncations = capTruncations(mergedTruncationsRaw, MAX_TRUNCATIONS);
+    const records = [...correlation.records].sort((a, b) => (a.runtimeTargetId < b.runtimeTargetId ? -1 : a.runtimeTargetId > b.runtimeTargetId ? 1 : 0));
+    if (records.length > MAX_CORRELATION_RECORDS) {
+        return { ok: false, reason: `correlation.records exceeds MAX_CORRELATION_RECORDS (${MAX_CORRELATION_RECORDS}); caller must bound before attaching` };
+    }
+    // CONTRACT-002: any known required loss introduced by this attach step
+    // (from correlation.omissions/correlation.truncations only - pre-existing
+    // artifact-level loss is left exactly as the artifact already represented
+    // it) forces inadequate; optional-only loss may downgrade adequate to
+    // partial; no loss leaves adequacy untouched.
+    const newRequiredOmissions = correlation.omissions.filter((o) => o.required);
+    const newRequiredTruncations = correlation.truncations.filter((t) => t.required);
+    const hasNewRequiredLoss = newRequiredOmissions.length > 0 || newRequiredTruncations.length > 0;
+    const hasNewOptionalLoss = correlation.omissions.some((o) => !o.required) || correlation.truncations.some((t) => !t.required);
+    let adequacy = artifact.adequacy;
+    if (hasNewRequiredLoss) {
+        const newReasonCodes = new Set([
+            ...newRequiredOmissions.map((o) => classifyRequiredAdequacyReason(o.subject, true)),
+            ...newRequiredTruncations.map((t) => classifyRequiredAdequacyReason(t.subject, false)),
+        ]);
+        const existingCodes = new Set(artifact.adequacy.reasons.map((r) => r.code));
+        const addedReasons = [...newReasonCodes].filter((code) => !existingCodes.has(code)).map((code) => ({ code }));
+        adequacy = { state: 'inadequate', reasons: [...artifact.adequacy.reasons, ...addedReasons] };
+    }
+    else if (artifact.adequacy.state === 'adequate' && hasNewOptionalLoss) {
+        // No ADEQUACY_REASON_CODE exists specifically for "optional correlation
+        // evidence truncated" (every truncation-specific code is required-loss
+        // scoped by name: `required-source-evidence-truncated`). Per
+        // CONTRACT-002/CONTRACT-001 (no new diagnostic field/code), the closest
+        // truthful existing non-required-scoped correlation code is reused, with
+        // the free-text `detail` field (already part of the frozen
+        // `AdequacyReason` shape) carrying the honest specifics.
+        adequacy = {
+            state: 'partial',
+            reasons: [
+                ...artifact.adequacy.reasons,
+                { code: REQUIRED_CANDIDATE_TRUNCATION_ADEQUACY_REASON, detail: 'optional-only correlation evidence was truncated by a bound; no required correlation evidence was lost' },
+            ],
+        };
+    }
+    if (!isValidAdequacy(adequacy))
+        return { ok: false, reason: 'internal adequacy recomputation produced an invalid Adequacy value' };
+    const nextArtifact = {
+        ...artifact,
+        omissions: mergedOmissions,
+        truncations: mergedTruncations,
+        adequacy,
+        ...(records.length > 0 ? { correlations: records } : {}),
+    };
+    const finalValidation = isValidBoundedAgentContextArtifact(nextArtifact);
+    if (!finalValidation.valid)
+        return { ok: false, reason: `internal attach produced an invalid artifact: ${finalValidation.reason}` };
+    return { ok: true, artifact: nextArtifact };
+}
+//# sourceMappingURL=boundedAgentContextCorrelation.js.map

package/dist/domain/boundedAgentContextCorrelation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundedAgentContextCorrelation.js","sourceRoot":"","sources":["../../src/domain/boundedAgentContextCorrelation.ts"],"names":[],"mappings":"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"}

package/dist/domain/boundedAgentContextIdentity.d.ts

@@ -0,0 +1,16 @@
+import type { BoundedAgentContextSourceReferences, ProjectionProfile } from './boundedAgentContext.js';
+/**
+ * Pure function of {sources (arrays sorted - order carries no semantic
+ * meaning here), targetIds (sorted), projectionProfile} only. Never includes
+ * an operational output location, a captured timestamp, or contextId - an
+ * operational output path must never affect logical identity, and equivalent
+ * semantic input must always produce the same identity regardless of the
+ * order targets were originally supplied in.
+ */
+export declare function buildBoundedAgentContextRequestIdentity(sources: BoundedAgentContextSourceReferences, targetIds: readonly string[], projectionProfile: ProjectionProfile): string;
+/**
+ * Fresh, opaque per-generated-instance identity - never derived from a
+ * timestamp alone, never collides even when called twice with the same
+ * requestIdentity within the same millisecond.
+ */
+export declare function buildBoundedAgentContextInstanceIdentity(requestIdentity: string): string;

package/dist/domain/boundedAgentContextIdentity.js

@@ -0,0 +1,53 @@
+import { createHash, randomBytes } from 'node:crypto';
+/**
+ * Deliberately duplicated from domain/identity.ts#canonicalize (and its other
+ * per-module duplicates) rather than imported - each identity module owns its
+ * own private canonicalize per existing repository convention. Same
+ * algorithm (sorted object keys, order-preserving arrays).
+ */
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value !== null && typeof value === 'object') {
+        const entries = Object.entries(value)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([key, entryValue]) => [key, canonicalize(entryValue)]);
+        return Object.fromEntries(entries);
+    }
+    return value;
+}
+/**
+ * Pure function of {sources (arrays sorted - order carries no semantic
+ * meaning here), targetIds (sorted), projectionProfile} only. Never includes
+ * an operational output location, a captured timestamp, or contextId - an
+ * operational output path must never affect logical identity, and equivalent
+ * semantic input must always produce the same identity regardless of the
+ * order targets were originally supplied in.
+ */
+export function buildBoundedAgentContextRequestIdentity(sources, targetIds, projectionProfile) {
+    const semanticView = {
+        sources: {
+            observationIds: [...sources.observationIds].sort(),
+            comparisonId: sources.comparisonId ?? null,
+            comparisonRequestId: sources.comparisonRequestId ?? null,
+            baselineContractId: sources.baselineContractId ?? null,
+            changeContractId: sources.changeContractId ?? null,
+            evaluationId: sources.evaluationId ?? null,
+            evaluationRequestId: sources.evaluationRequestId ?? null,
+        },
+        targetIds: [...targetIds].sort(),
+        projectionProfile,
+    };
+    const serialized = JSON.stringify(canonicalize(semanticView));
+    return createHash('sha256').update(serialized).digest('hex');
+}
+/**
+ * Fresh, opaque per-generated-instance identity - never derived from a
+ * timestamp alone, never collides even when called twice with the same
+ * requestIdentity within the same millisecond.
+ */
+export function buildBoundedAgentContextInstanceIdentity(requestIdentity) {
+    const nonce = randomBytes(16).toString('hex');
+    return `${requestIdentity}-${nonce}`;
+}
+//# sourceMappingURL=boundedAgentContextIdentity.js.map

package/dist/domain/boundedAgentContextIdentity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundedAgentContextIdentity.js","sourceRoot":"","sources":["../../src/domain/boundedAgentContextIdentity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGtD;;;;;GAKG;AACH,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACzD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC;aAC7D,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;aAChD,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,YAAY,CAAC,UAAU,CAAC,CAAU,CAAC,CAAC;QACxE,OAAO,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,uCAAuC,CACrD,OAA4C,EAC5C,SAA4B,EAC5B,iBAAoC;IAEpC,MAAM,YAAY,GAAG;QACnB,OAAO,EAAE;YACP,cAAc,EAAE,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,IAAI,EAAE;YAClD,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,IAAI;YAC1C,mBAAmB,EAAE,OAAO,CAAC,mBAAmB,IAAI,IAAI;YACxD,kBAAkB,EAAE,OAAO,CAAC,kBAAkB,IAAI,IAAI;YACtD,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,IAAI,IAAI;YAClD,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,IAAI;YAC1C,mBAAmB,EAAE,OAAO,CAAC,mBAAmB,IAAI,IAAI;SACzD;QACD,SAAS,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,IAAI,EAAE;QAChC,iBAAiB;KAClB,CAAC;IACF,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC;IAC9D,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC/D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wCAAwC,CAAC,eAAuB;IAC9E,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC9C,OAAO,GAAG,eAAe,IAAI,KAAK,EAAE,CAAC;AACvC,CAAC"}