@evomap/evolver-core 2.0.0-beta.19 → 2.0.0-beta.22

package/dist/signals/expand.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 // Signal expansion & tag classification (ported from v1 src/gep/learningSignals.js).
 // Raw signals (e.g. '429') are expanded into broader semantic tags (e.g. 'problem:reliability',
 // 'action:repair') so gene selection can match by MEANING, not just literal string intersection —
@@ -41,6 +42,18 @@ const EXPANSION_RULES = [
     { re: /(tool_bypass|tool_loop|工具绕过|工具循环|ツール迂回|ツールループ|도구우회|도구반복)/, tags: ['area:orchestration', 'risk:validation'] },
     { re: /(memory|narrative|reflection)/, tags: ['area:memory'] },
     { re: /(skill|dashboard)/, tags: ['area:skills'] },
+    // Harness context budget (v1 context-compression gene family port): an agent harness that injects large
+    // tool/MCP schemas, long skill manuals, agent-type descriptions, a memory index, or a pasted transcript can
+    // exhaust the model's context window before the task starts. That is a prompt-assembly (area:prompt) cost
+    // problem, and shrinking it is an optimize action — NOT a reliability failure. v2 has no seed-gene catalog,
+    // so these rules ARE the shared vocabulary that lets a context-bloat signal reach a compression strategy.
+    { re: /(context_bloat|context_explosion|context window|token_budget|prompt_budget|上下文爆|上下文预算|token 超限|token超限)/, tags: ['problem:context_budget', 'action:optimize', 'area:prompt'] },
+    // Tool/MCP schema weight is the always-on half of the budget; lazy-loading it is the corrective action.
+    { re: /(tool_schema|schema_bloat|mcp_tool_schema|lazy_load_schema|just-in-time schema|工具 schema|工具schema)/, tags: ['problem:context_budget', 'action:optimize', 'area:prompt', 'area:orchestration'] },
+    // Skill manuals / agent-type descriptions are the other always-on half (area:skills already exists above).
+    { re: /(skill_list_bloat|skill_manual_bloat|agent type description|mcp server instructions|skill 列表太长|技能列表太长)/, tags: ['problem:context_budget', 'action:optimize', 'area:skills', 'area:prompt'] },
+    // A pasted transcript / session handoff is the caller-supplied half — compressing it is a memory-shaped concern.
+    { re: /(transcript_bloat|transcript_context_bloat|conversation_handoff|session handoff|pasted transcript|会话上下文就爆|完整转录)/, tags: ['problem:context_budget', 'action:optimize', 'area:memory'] },
     { re: /(validation|canary|rollback|constraint|blast radius|destructive)/, tags: ['risk:validation'] },
 ];
 /**
@@ -142,4 +155,139 @@ export function tagOverlapScore(signals, gene) {
         if (geneTagSet.has(t))
             hits++;
     return hits / sigTags.length;
+}
+const SEMANTIC_IDF_DOCUMENT_LIMIT = 1_000;
+const SEMANTIC_IDF_TEXT_CHARS_PER_DOCUMENT = 4_096;
+const SEMANTIC_IDF_TAG_INPUTS_PER_DOCUMENT = 256;
+const SEMANTIC_IDF_TAG_CHARS = 1_024;
+const SEMANTIC_IDF_TAGS_PER_DOCUMENT = 64;
+const SEMANTIC_IDF_TOKENS_PER_DOCUMENT = 128;
+const SEMANTIC_IDF_TAG_VOCABULARY_LIMIT = 8_192;
+const SEMANTIC_IDF_TOKEN_VOCABULARY_LIMIT = 32_768;
+function normalizeSemanticTag(tag) {
+    return tag.normalize('NFKC').trim().toLowerCase();
+}
+function inverseDocumentFrequency(documentCount, documentFrequency) {
+    return Math.log(documentCount / documentFrequency);
+}
+function tokenFrequency(text) {
+    const frequencies = new Map();
+    for (const token of tokenize(text)) {
+        frequencies.set(token, (frequencies.get(token) ?? 0) + 1);
+    }
+    return frequencies;
+}
+function compareCodeUnits(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function boundedUnique(values, limit) {
+    return [...new Set(values.filter(Boolean))].sort(compareCodeUnits).slice(0, limit);
+}
+function boundedVocabulary(valuesByDocument, limit) {
+    const vocabulary = new Set();
+    for (const values of valuesByDocument) {
+        for (const value of values)
+            vocabulary.add(value);
+    }
+    // Selecting by code-unit order makes the cap independent of corpus/document order. The source set is itself
+    // bounded by the per-document and document-count limits above, so this sort cannot grow without bound.
+    return new Set([...vocabulary].sort(compareCodeUnits).slice(0, limit));
+}
+function semanticProfileVersion(documentCount, tagDocumentFrequency, tokenDocumentFrequency) {
+    // Hash only normalized document-frequency entries so decision telemetry never contains plaintext corpus data.
+    // A 128-bit SHA-256 prefix keeps the identifier compact while avoiding the collision rate of a 32-bit checksum.
+    const hash = createHash('sha256');
+    hash.update(`documents:${documentCount};`, 'utf8');
+    for (const [tag, frequency] of [...tagDocumentFrequency].sort(([left], [right]) => compareCodeUnits(left, right))) {
+        hash.update(`tag:${tag.length}:${tag}:${frequency};`, 'utf8');
+    }
+    for (const [token, frequency] of [...tokenDocumentFrequency].sort(([left], [right]) => compareCodeUnits(left, right))) {
+        hash.update(`token:${token.length}:${token}:${frequency};`, 'utf8');
+    }
+    return `idf-2:n=${documentCount};tags=${tagDocumentFrequency.size};tokens=${tokenDocumentFrequency.size};sha256=${hash.digest('hex').slice(0, 32)}`;
+}
+export function buildSemanticIdfProfile(documents) {
+    const boundedDocuments = documents.slice(0, SEMANTIC_IDF_DOCUMENT_LIMIT).map((document) => ({
+        tags: boundedUnique(document.tags
+            .slice(0, SEMANTIC_IDF_TAG_INPUTS_PER_DOCUMENT)
+            .map((tag) => normalizeSemanticTag(tag.slice(0, SEMANTIC_IDF_TAG_CHARS))), SEMANTIC_IDF_TAGS_PER_DOCUMENT),
+        tokens: boundedUnique(tokenize(document.text.slice(0, SEMANTIC_IDF_TEXT_CHARS_PER_DOCUMENT)), SEMANTIC_IDF_TOKENS_PER_DOCUMENT),
+    }));
+    const tagVocabulary = boundedVocabulary(boundedDocuments.map((document) => document.tags), SEMANTIC_IDF_TAG_VOCABULARY_LIMIT);
+    const tokenVocabulary = boundedVocabulary(boundedDocuments.map((document) => document.tokens), SEMANTIC_IDF_TOKEN_VOCABULARY_LIMIT);
+    const tagDocumentFrequency = new Map();
+    const tokenDocumentFrequency = new Map();
+    for (const document of boundedDocuments) {
+        for (const tag of document.tags) {
+            if (!tagVocabulary.has(tag))
+                continue;
+            tagDocumentFrequency.set(tag, (tagDocumentFrequency.get(tag) ?? 0) + 1);
+        }
+        for (const token of document.tokens) {
+            if (!tokenVocabulary.has(token))
+                continue;
+            tokenDocumentFrequency.set(token, (tokenDocumentFrequency.get(token) ?? 0) + 1);
+        }
+    }
+    const documentCount = boundedDocuments.length;
+    const tagIdf = new Map();
+    const tokenIdf = new Map();
+    for (const [tag, frequency] of tagDocumentFrequency) {
+        tagIdf.set(tag, inverseDocumentFrequency(documentCount, frequency));
+    }
+    for (const [token, frequency] of tokenDocumentFrequency) {
+        tokenIdf.set(token, inverseDocumentFrequency(documentCount, frequency));
+    }
+    return {
+        documentCount,
+        tagIdf,
+        tokenIdf,
+        version: semanticProfileVersion(documentCount, tagDocumentFrequency, tokenDocumentFrequency),
+    };
+}
+export function idfTagOverlapScore(signals, gene, profile) {
+    if (profile.documentCount <= 1)
+        return tagOverlapScore(signals, gene);
+    const signalTags = [...new Set(expandSignals(signals).map(normalizeSemanticTag))];
+    const geneTagSet = new Set(geneTags(gene).map(normalizeSemanticTag));
+    let matchedWeight = 0;
+    let totalWeight = 0;
+    for (const tag of signalTags) {
+        const weight = profile.tagIdf.get(tag);
+        if (weight === undefined)
+            continue;
+        totalWeight += weight;
+        if (geneTagSet.has(tag))
+            matchedWeight += weight;
+    }
+    return totalWeight > 0 ? matchedWeight / totalWeight : 0;
+}
+export function idfBagCosine(a, b, profile) {
+    if (profile.documentCount <= 1)
+        return bagCosine(a, b);
+    const bagA = tokenFrequency(a);
+    const bagB = tokenFrequency(b);
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (const [token, count] of bagA) {
+        const weight = profile.tokenIdf.get(token);
+        if (weight === undefined)
+            continue;
+        const weightedCount = count * weight;
+        normA += weightedCount * weightedCount;
+        const otherCount = bagB.get(token);
+        if (otherCount !== undefined)
+            dot += weightedCount * otherCount * weight;
+    }
+    for (const [token, count] of bagB) {
+        const weight = profile.tokenIdf.get(token);
+        if (weight === undefined)
+            continue;
+        const weightedCount = count * weight;
+        normB += weightedCount * weightedCount;
+    }
+    if (normA === 0 || normB === 0)
+        return 0;
+    return dot / (Math.sqrt(normA) * Math.sqrt(normB));
 }

package/dist/signals/index.d.ts

@@ -4,4 +4,6 @@ export * from './expand.js';
 export * from './traceSignals.js';
 export * from './metaSignals.js';
 export * from './cycleHistoryFromEvents.js';
-export * from './curriculum.js';
+export * from './curriculum.js';
+export * from './taskDomain.js';
+export * from './scopeVocabulary.js';

package/dist/signals/index.js

@@ -4,4 +4,6 @@ export * from './expand.js';
 export * from './traceSignals.js';
 export * from './metaSignals.js';
 export * from './cycleHistoryFromEvents.js';
-export * from './curriculum.js';
+export * from './curriculum.js';
+export * from './taskDomain.js';
+export * from './scopeVocabulary.js';

package/dist/signals/scopeVocabulary.d.ts

@@ -0,0 +1,75 @@
+import type { AssetStoreProvider, AssetRecord } from '../assetstore/provider.js';
+/** A signal observed in the store, with how many assets declare it. */
+export interface ScopeVocabularyEntry {
+    signal: string;
+    /** Number of Gene assets whose signals_match declares this signal (hard facets counted by their bare tag). */
+    assetCount: number;
+}
+export interface ScopeVocabulary {
+    /** Observed signals, most-declared first. */
+    entries: ScopeVocabularyEntry[];
+    /** Convenience set of the bare signal strings. */
+    signals: Set<string>;
+}
+/** Strip a `required:` facet prefix to get the bare signal a facet gates on. */
+export declare function bareSignal(tag: string): string;
+/**
+ * Build the scope vocabulary from a set of Gene asset records already in hand. Hard facets contribute their BARE
+ * signal, because `required:rounding-v2` and `rounding-v2` refer to the same scope dimension — one gates on it,
+ * one hints at it. Factored out of {@link deriveScopeVocabulary} so a caller that ALREADY holds the gene records
+ * (e.g. the distiller, which lists existing genes for dedup anyway) can build the same vocabulary without a second
+ * store round-trip, and so the prompt-injection path and the post-hoc resolve path share ONE derivation.
+ */
+export declare function scopeVocabularyFromRecords(records: readonly AssetRecord[]): ScopeVocabulary;
+/**
+ * Derive the scope vocabulary from the Gene assets in a store. Thin async wrapper over
+ * {@link scopeVocabularyFromRecords} that fetches the records first.
+ */
+export declare function deriveScopeVocabulary(store: AssetStoreProvider, limit?: number): Promise<ScopeVocabulary>;
+export type ScopeResolution = 
+/** The proposed tag names a signal that exists; usable as-is. */
+{
+    status: 'exact';
+    proposed: string;
+    resolved: string;
+}
+/**
+ * The proposed tag does not exist, but exactly ONE observed signal is an unambiguous refinement of it — the
+ * autonomous-scope failure mode, where `v2` was proposed and `rounding-v2` is what exists. `resolved` is the
+ * real signal; a caller may adopt it, or surface it for review.
+ */
+ | {
+    status: 'resolved';
+    proposed: string;
+    resolved: string;
+    reason: string;
+}
+/** Several observed signals match equally well; resolving would be a guess, so we refuse to pick. */
+ | {
+    status: 'ambiguous';
+    proposed: string;
+    candidates: string[];
+}
+/** Nothing in the store resembles the tag. Not an error: a genuinely new scope looks like this. */
+ | {
+    status: 'unknown';
+    proposed: string;
+};
+/**
+ * Resolve a proposed scope tag against an observed vocabulary.
+ *
+ * Matching is deliberately conservative. Beyond an exact hit we accept only ONE relation: an observed signal that
+ * ends with `-<proposed>` or `_<proposed>` (or begins with `<proposed>-`/`<proposed>_`), i.e. the proposal is a
+ * bare qualifier and the real signal is that qualifier scoped to a domain. That is exactly the `v2` →
+ * `rounding-v2` shape. We do NOT do fuzzy/edit-distance matching: silently rewriting a scope key on a weak
+ * similarity signal would be a governance hazard far worse than an unresolved tag, since scope decides what gets
+ * injected into an agent's context. Multiple candidates yield `ambiguous` rather than an arbitrary pick.
+ */
+export declare function resolveScopeTag(proposed: string, vocab: ScopeVocabulary): ScopeResolution;
+/**
+ * Render the vocabulary as a compact, promptable list. This is what makes the vocabulary \emph{discoverable} to a
+ * distiller: it can be shown the signals that exist before being asked to choose a facet, instead of guessing.
+ * Bounded by `max` so a large store cannot blow a prompt budget; the most-declared signals come first, and the
+ * count is reported so a reader can tell a load-bearing scope from a one-off tag.
+ */
+export declare function renderScopeVocabulary(vocab: ScopeVocabulary, max?: number): string;

package/dist/signals/scopeVocabulary.js

@@ -0,0 +1,91 @@
+const REQUIRED_PREFIX = 'required:';
+/** Strip a `required:` facet prefix to get the bare signal a facet gates on. */
+export function bareSignal(tag) {
+    const t = String(tag).trim();
+    return t.startsWith(REQUIRED_PREFIX) ? t.slice(REQUIRED_PREFIX.length).trim() : t;
+}
+function asStrings(v) {
+    return Array.isArray(v) ? v.filter((x) => typeof x === 'string') : [];
+}
+/**
+ * Build the scope vocabulary from a set of Gene asset records already in hand. Hard facets contribute their BARE
+ * signal, because `required:rounding-v2` and `rounding-v2` refer to the same scope dimension — one gates on it,
+ * one hints at it. Factored out of {@link deriveScopeVocabulary} so a caller that ALREADY holds the gene records
+ * (e.g. the distiller, which lists existing genes for dedup anyway) can build the same vocabulary without a second
+ * store round-trip, and so the prompt-injection path and the post-hoc resolve path share ONE derivation.
+ */
+export function scopeVocabularyFromRecords(records) {
+    const counts = new Map();
+    for (const g of records) {
+        // One asset counts once per distinct signal, so a repeated tag within one asset cannot inflate the count.
+        const seen = new Set();
+        for (const raw of asStrings(g['signals_match'])) {
+            const s = bareSignal(raw);
+            if (!s || seen.has(s))
+                continue;
+            seen.add(s);
+            counts.set(s, (counts.get(s) ?? 0) + 1);
+        }
+    }
+    const entries = [...counts.entries()]
+        .map(([signal, assetCount]) => ({ signal, assetCount }))
+        .sort((a, b) => b.assetCount - a.assetCount || a.signal.localeCompare(b.signal));
+    return { entries, signals: new Set(entries.map((e) => e.signal)) };
+}
+/**
+ * Derive the scope vocabulary from the Gene assets in a store. Thin async wrapper over
+ * {@link scopeVocabularyFromRecords} that fetches the records first.
+ */
+export async function deriveScopeVocabulary(store, limit = 500) {
+    return scopeVocabularyFromRecords(await store.list('Gene', limit));
+}
+/**
+ * Resolve a proposed scope tag against an observed vocabulary.
+ *
+ * Matching is deliberately conservative. Beyond an exact hit we accept only ONE relation: an observed signal that
+ * ends with `-<proposed>` or `_<proposed>` (or begins with `<proposed>-`/`<proposed>_`), i.e. the proposal is a
+ * bare qualifier and the real signal is that qualifier scoped to a domain. That is exactly the `v2` →
+ * `rounding-v2` shape. We do NOT do fuzzy/edit-distance matching: silently rewriting a scope key on a weak
+ * similarity signal would be a governance hazard far worse than an unresolved tag, since scope decides what gets
+ * injected into an agent's context. Multiple candidates yield `ambiguous` rather than an arbitrary pick.
+ */
+export function resolveScopeTag(proposed, vocab) {
+    const bare = bareSignal(proposed);
+    if (!bare)
+        return { status: 'unknown', proposed };
+    if (vocab.signals.has(bare))
+        return { status: 'exact', proposed, resolved: bare };
+    const lower = bare.toLowerCase();
+    const candidates = [...vocab.signals].filter((s) => {
+        const sl = s.toLowerCase();
+        if (sl === lower)
+            return true;
+        return sl.endsWith(`-${lower}`) || sl.endsWith(`_${lower}`)
+            || sl.startsWith(`${lower}-`) || sl.startsWith(`${lower}_`);
+    });
+    if (candidates.length === 1) {
+        return {
+            status: 'resolved',
+            proposed,
+            resolved: candidates[0],
+            reason: `proposed '${bare}' is a bare qualifier; the store's vocabulary declares '${candidates[0]}'`,
+        };
+    }
+    if (candidates.length > 1)
+        return { status: 'ambiguous', proposed, candidates: candidates.sort() };
+    return { status: 'unknown', proposed };
+}
+/**
+ * Render the vocabulary as a compact, promptable list. This is what makes the vocabulary \emph{discoverable} to a
+ * distiller: it can be shown the signals that exist before being asked to choose a facet, instead of guessing.
+ * Bounded by `max` so a large store cannot blow a prompt budget; the most-declared signals come first, and the
+ * count is reported so a reader can tell a load-bearing scope from a one-off tag.
+ */
+export function renderScopeVocabulary(vocab, max = 40) {
+    if (vocab.entries.length === 0)
+        return '(no signals observed in this store yet)';
+    const shown = vocab.entries.slice(0, max);
+    const body = shown.map((e) => `${e.signal} (${e.assetCount})`).join(', ');
+    const omitted = vocab.entries.length - shown.length;
+    return omitted > 0 ? `${body}, ... and ${omitted} more` : body;
+}

package/dist/signals/taskDomain.d.ts

@@ -0,0 +1,22 @@
+export declare const TASK_DOMAIN_SIGNAL_PREFIX: "task_domain:";
+export type TaskDomainResolution = {
+    status: 'absent';
+} | {
+    status: 'resolved';
+    slug: string;
+} | {
+    status: 'ambiguous';
+} | {
+    status: 'invalid';
+};
+/** Identify the namespace even when the value is malformed, so it cannot leak into generic matching. */
+export declare function isTaskDomainSignal(raw: string): boolean;
+/** Remove task-domain tokens from generic matching while preserving their original wire representation elsewhere. */
+export declare function withoutTaskDomainSignals(signals: readonly string[]): string[];
+/**
+ * Resolve one canonical task domain from signal tokens. Parsing is order-independent and fail-closed:
+ * malformed tokens invalidate the whole dimension, and distinct valid slugs are ambiguous.
+ */
+export declare function resolveTaskDomainSignals(signals: readonly string[]): TaskDomainResolution;
+/** Emit a canonical wire token. Callers must supply an already-normalized lowercase slug. */
+export declare function taskDomainSignal(slug: string): string;

package/dist/signals/taskDomain.js

@@ -0,0 +1,43 @@
+export const TASK_DOMAIN_SIGNAL_PREFIX = 'task_domain:';
+const TASK_DOMAIN_SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** Identify the namespace even when the value is malformed, so it cannot leak into generic matching. */
+export function isTaskDomainSignal(raw) {
+    return raw.trim().toLowerCase().startsWith(TASK_DOMAIN_SIGNAL_PREFIX);
+}
+/** Remove task-domain tokens from generic matching while preserving their original wire representation elsewhere. */
+export function withoutTaskDomainSignals(signals) {
+    return signals.filter((signal) => !isTaskDomainSignal(signal));
+}
+/**
+ * Resolve one canonical task domain from signal tokens. Parsing is order-independent and fail-closed:
+ * malformed tokens invalidate the whole dimension, and distinct valid slugs are ambiguous.
+ */
+export function resolveTaskDomainSignals(signals) {
+    const slugs = new Set();
+    let found = false;
+    for (const raw of signals) {
+        const signal = raw.trim();
+        const lower = signal.toLowerCase();
+        if (!lower.startsWith(TASK_DOMAIN_SIGNAL_PREFIX))
+            continue;
+        found = true;
+        if (signal !== raw)
+            return { status: 'invalid' };
+        const slug = lower.slice(TASK_DOMAIN_SIGNAL_PREFIX.length);
+        if (!TASK_DOMAIN_SLUG_RE.test(slug))
+            return { status: 'invalid' };
+        slugs.add(slug);
+    }
+    if (!found)
+        return { status: 'absent' };
+    if (slugs.size !== 1)
+        return { status: 'ambiguous' };
+    return { status: 'resolved', slug: slugs.values().next().value };
+}
+/** Emit a canonical wire token. Callers must supply an already-normalized lowercase slug. */
+export function taskDomainSignal(slug) {
+    if (!TASK_DOMAIN_SLUG_RE.test(slug)) {
+        throw new Error(`invalid task_domain slug: ${slug}`);
+    }
+    return `${TASK_DOMAIN_SIGNAL_PREFIX}${slug}`;
+}

package/dist/trace/learningTrace.d.ts

@@ -107,6 +107,13 @@ export declare class AgentRunTraceRecorder {
     private readonly recorded;
     constructor(opts: AgentRunTraceRecorderOptions);
     get events(): readonly TraceEvent[];
+    get sessionId(): string | undefined;
+    /**
+     * Late-bind a session id discovered after run start (e.g. unique proxy llm_turn session).
+     * Backfills already-recorded events so the whole trajectory carries the join key.
+     * Fail closed on empty/whitespace values and conflicting rebinds.
+     */
+    bindSessionId(sessionId: string): void;
     runStarted(input?: RunStartedInput): TraceEvent;
     modelCalled(input?: ModelCalledInput): TraceEvent;
     toolCalled(input: ToolCalledInput): TraceEvent;

package/dist/trace/learningTrace.js

@@ -53,6 +53,28 @@ export class AgentRunTraceRecorder {
         this.opts = opts;
     }
     get events() { return this.recorded; }
+    get sessionId() { return this.opts.sessionId; }
+    /**
+     * Late-bind a session id discovered after run start (e.g. unique proxy llm_turn session).
+     * Backfills already-recorded events so the whole trajectory carries the join key.
+     * Fail closed on empty/whitespace values and conflicting rebinds.
+     */
+    bindSessionId(sessionId) {
+        const next = sessionId.trim();
+        if (next.length === 0) {
+            throw new Error('sessionId must be a non-empty string');
+        }
+        const current = this.opts.sessionId;
+        if (current !== undefined) {
+            if (current === next)
+                return;
+            throw new Error(`sessionId already bound to ${current}; refusing to rebind to ${next}`);
+        }
+        this.opts.sessionId = next;
+        for (const event of this.recorded) {
+            event.sessionId = next;
+        }
+    }
     runStarted(input = {}) {
         return this.record('run.started', {
             ...(input.taskSummary !== undefined ? { taskSummary: input.taskSummary } : {}),

package/dist/trace/trajectory.d.ts

@@ -78,5 +78,13 @@ export interface TraceTrajectoryDraft {
     coverage: TraceCoverageItem[];
 }
 export declare function traceRecordToTurnDraft(record: NativeTraceRecord): TraceTurnDraft | null;
+/**
+ * Exact-join helper for Learning Ops: return the unique non-empty session id across turns.
+ * Fail closed — 0 or >1 distinct ids yield null. Matches the correlation key contract used by
+ * Darwin (`cc::<session_id>` ↔ packet `traceEvents[].sessionId`).
+ */
+export declare function uniqueSessionId(turns: readonly {
+    session_id?: string | null;
+}[]): string | null;
 export declare function buildTraceTrajectoryDraft(records: readonly NativeTraceRecord[]): TraceTrajectoryDraft;
 export declare function coverageForTurns(turns: readonly TraceTurnDraft[]): TraceCoverageItem[];

package/dist/trace/trajectory.js

@@ -95,12 +95,24 @@ export function traceRecordToTurnDraft(record) {
         ...(validation !== undefined ? { validation } : {}),
     };
 }
+/**
+ * Exact-join helper for Learning Ops: return the unique non-empty session id across turns.
+ * Fail closed — 0 or >1 distinct ids yield null. Matches the correlation key contract used by
+ * Darwin (`cc::<session_id>` ↔ packet `traceEvents[].sessionId`).
+ */
+export function uniqueSessionId(turns) {
+    const sessionIds = [
+        ...new Set(turns
+            .map((turn) => turn.session_id)
+            .filter((value) => typeof value === 'string' && value.length > 0)),
+    ];
+    return sessionIds.length === 1 ? sessionIds[0] : null;
+}
 export function buildTraceTrajectoryDraft(records) {
     const turns = records.map(traceRecordToTurnDraft).filter((turn) => turn !== null);
-    const sessionIds = [...new Set(turns.map((turn) => turn.session_id).filter((value) => typeof value === 'string' && value.length > 0))];
     return {
         schema: 'evolver_trace_trajectory_draft.v1',
-        session_id: sessionIds.length === 1 ? sessionIds[0] : null,
+        session_id: uniqueSessionId(turns),
         turns,
         coverage: coverageForTurns(turns),
     };

package/dist/util/fileLock.d.ts

@@ -1,35 +1,122 @@
 export declare function syncSleep(ms: number): void;
+export type FileLockProcessStartIdentity = {
+    readonly source: 'linux-proc';
+    readonly bootId: string;
+    readonly startTicks: string;
+} | {
+    readonly source: 'windows-powershell';
+    readonly startTimeTicks: string;
+} | {
+    readonly source: 'darwin-ps';
+    readonly startTime: string;
+};
+export interface FileLockOwnerRecord {
+    readonly pid: number;
+    readonly token: string;
+    readonly processStartIdentity: FileLockProcessStartIdentity;
+}
+export type TransferLockOwnershipReason = 'transferred' | 'not_owned' | 'ownership_changed' | 'mutation_busy' | 'guardian_exists' | 'guardian_missing' | 'target_process_dead' | 'target_process_pid_reused' | 'target_process_unverifiable' | 'path_changed';
+export type TransferLockOwnershipResult = {
+    transferred: true;
+    reason: 'transferred';
+    guardian: FileLockOwnerRecord;
+} | {
+    transferred: false;
+    reason: Exclude<TransferLockOwnershipReason, 'transferred'>;
+};
+export type AttachLockGuardianResult = {
+    attached: true;
+    reason: 'attached';
+    guardian: FileLockOwnerRecord;
+} | {
+    attached: false;
+    reason: Exclude<TransferLockOwnershipReason, 'transferred'>;
+};
+export type RetainLockGuardianResult = {
+    retained: true;
+    reason: 'retained';
+} | {
+    retained: false;
+    reason: 'not_owned' | 'ownership_changed' | 'mutation_busy' | 'guardian_missing' | 'path_changed';
+};
+export type ClearLockGuardianResult = {
+    cleared: true;
+    reason: 'cleared' | 'missing';
+} | {
+    cleared: false;
+    reason: 'not_owned' | 'ownership_changed' | 'mutation_busy' | 'path_changed';
+};
+export type FileLockOwnerProcessStatus = 'current' | 'dead' | 'pid_reused' | 'unverifiable';
 export declare class LockTimeoutError extends Error {
     readonly code = "LOCK_TIMEOUT";
     constructor(_lockPath?: string);
 }
-export type UnsafeLockPathReason = 'symlink' | 'not_regular_file' | 'owner_too_large' | 'path_changed' | 'permission_denied' | 'invalid_owner';
+export type UnsafeLockPathReason = 'symlink' | 'not_regular_file' | 'owner_too_large' | 'path_changed' | 'permission_denied' | 'process_identity_unavailable' | 'invalid_owner';
 export declare class UnsafeLockPathError extends Error {
     readonly reason: UnsafeLockPathReason;
     readonly code = "UNSAFE_LOCK_PATH";
     constructor(reason: UnsafeLockPathReason);
 }
 export declare const MAX_LOCK_OWNER_BYTES = 4096;
+/** Fresh native process-start observation. Unlike lock acquisition, this does not use caches. */
+export declare function readFileLockProcessStartIdentity(pid: number): FileLockProcessStartIdentity | null;
+export declare function sameFileLockProcessStartIdentity(left: FileLockProcessStartIdentity, right: FileLockProcessStartIdentity): boolean;
+export declare function parseFileLockProcessStartIdentity(value: unknown): FileLockProcessStartIdentity | undefined;
+/**
+ * Conservative owner classification for crash recovery. PID reuse and unavailable identity
+ * remain distinct from a proven-dead PID so callers cannot reclaim ambiguous ownership.
+ */
+export declare function inspectFileLockOwnerProcess(owner: Pick<FileLockOwnerRecord, 'pid' | 'processStartIdentity'>): FileLockOwnerProcessStatus;
+export declare function _setFileLockTestHooksForTest(hooks?: {
+    processStartIdentity?: (pid: number) => FileLockProcessStartIdentity | null;
+    pidAlive?: (pid: number) => boolean;
+    beforeOwnerPublish?: (temporaryPath: string, lockPath: string) => void;
+    beforeGuardianPublish?: (temporaryPath: string, guardianPath: string) => void;
+    afterGuardianPublish?: (guardianPath: string, lockPath: string) => void;
+    beforeGuardianReclaim?: (guardianPath: string, lockPath: string) => void;
+    beforeMutationGuardRelease?: (mutationGuardPath: string, lockPath: string) => void;
+}): void;
+/**
+ * Pre-arm an acquired lock with the exact child PID generation while retaining local ownership.
+ * A controller can therefore keep mutating its journal, while a hard controller crash cannot make
+ * the primary owner reclaimable until the child exits.
+ */
+export declare function attachLockGuardianToProcess(lockPath: string, expectedOwner: FileLockOwnerRecord, targetPid: number): AttachLockGuardianResult;
+/**
+ * Drop local ownership only after an already-published guardian has been revalidated exactly.
+ * No file mutation is needed: the durable guardian receipt is the crash-safe owner binding.
+ */
+export declare function retainLockGuardianForProcess(lockPath: string, expectedOwner: FileLockOwnerRecord, expectedGuardian: FileLockOwnerRecord): RetainLockGuardianResult;
+/**
+ * Remove an exact attached guardian after the child has definitely exited, retaining the primary
+ * owner so rollback or another launch can continue under the same lifecycle lease.
+ */
+export declare function clearLockGuardianForProcess(lockPath: string, expectedOwner: FileLockOwnerRecord, expectedGuardian: FileLockOwnerRecord): ClearLockGuardianResult;
+/**
+ * Atomically bind an acquired lock to a still-running child and relinquish local ownership.
+ */
+export declare function transferLockOwnershipToProcess(lockPath: string, expectedOwner: FileLockOwnerRecord, targetPid: number): TransferLockOwnershipResult;
 export interface AcquireLockOptions {
     maxTries?: number;
     waitMs?: number;
 }
 /**
- * Cross-process O_EXCL file lock with crashed-owner recovery.
+ * Cross-process file lock with crashed-owner recovery.
  *
  * The lock file records the owner pid and token. If a waiter finds the lock held by a pid that is no longer
  * alive (the owner crashed without releaseLock), it reclaims the stale lock instead of spinning
  * until timeout — otherwise one crashed process would deadlock every future writer until the file
  * is removed by hand. Empty or truncated locks are reclaimed only after the same inode and contents
  * remain malformed for a grace period, so a live creator can finish publishing its owner payload.
- * Acquisition stays atomic (O_EXCL), and stale reclaim moves the old lock aside under a mutation
- * guard, then verifies the inode snapshot before deletion. A live owner's lock (including this
+ * Acquisition publishes a fully synced temporary owner with an atomic no-replace hardlink, and stale
+ * reclaim moves the old lock aside under a mutation guard, then verifies the inode snapshot before
+ * deletion. A live owner's lock (including this
  * process's own) is never stolen.
  *
  * NOTE: still synchronous (blocks the event loop while waiting) by design — it guards short
  * synchronous critical sections (append-only writes).
  */
-export declare function acquireLock(lockPath: string, opts?: AcquireLockOptions): void;
+export declare function acquireLock(lockPath: string, opts?: AcquireLockOptions): FileLockOwnerRecord;
 export type ReleaseLockReason = 'released' | 'missing' | 'ownership_changed' | 'not_owned' | 'released_with_cleanup_error' | UnsafeLockPathReason | 'release_failed';
 export interface ReleaseLockResult {
     released: boolean;