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

package/dist/assetstore/provenance.js

@@ -4,9 +4,19 @@
 // must not enter the content hash (#30.2), or it would break content-addressing. Trust-first by construction:
 // selection defaults to trusted-only; an untrusted asset is promoted to trusted only by an explicit, logged act.
 import { join, dirname } from 'node:path';
-import { assertCapsuleGeneBinding, normalizeForPut, supportsAtomicConditionalPut, validateConditionalPutResult, } from './provider.js';
+import { assertCapsuleGeneBinding, FrozenAssetIdCollisionError, InvalidFrozenPutResultError, frozenAssetRecordsEqual, normalizeForPut, supportsAtomicConditionalPut, supportsAtomicFrozenConditionalPut, validateConditionalPutResult, validateFrozenPutResult, } from './provider.js';
 import { appendUtf8Durable, assertAssetStoreDirectory, ensureAssetStoreDirectory, readUtf8Regular, regularFileFingerprint, truncateUtf8SuffixDurable, withAssetStoreLock, } from './assetStoreStorage.js';
 import { assertTrustSidecarHealthy, parseProvenanceRecord, parseSidecarJsonl, } from './assetSidecarRecords.js';
+import { computeAssetId } from '../wire/index.js';
+export class ProvenanceWritePendingError extends Error {
+    assetId;
+    code = 'PROVENANCE_WRITE_PENDING';
+    constructor(assetId) {
+        super('asset provenance write is pending');
+        this.assetId = assetId;
+        this.name = 'ProvenanceWritePendingError';
+    }
+}
 function immutableRecord(record) {
     return Object.freeze({ ...record });
 }
@@ -69,6 +79,111 @@ export class ProvenanceStore {
             return this.appendUnderLock(full);
         });
     }
+    /** Stage a verified Hub write without replacing an in-flight conservative marker. */
+    stageUntrustedWriteTracked(assetId, source) {
+        assertAssetStoreDirectory(dirname(this.path));
+        return withAssetStoreLock(this.lockPath, () => {
+            this.refreshUnderLock();
+            const current = this.index.get(assetId);
+            if (current && (current.trusted === true || current.decision !== undefined)) {
+                return { record: current, appended: false };
+            }
+            if (current?.trusted === false) {
+                return { record: current, appended: false };
+            }
+            return {
+                record: this.appendUnderLock({
+                    assetId,
+                    source,
+                    trusted: false,
+                    at: new Date(this.now()).toISOString(),
+                }),
+                appended: true,
+            };
+        });
+    }
+    /** Finalize a verified write unless an operator made an explicit decision during I/O. */
+    finalizeUntrustedWrite(assetId, source) {
+        assertAssetStoreDirectory(dirname(this.path));
+        return withAssetStoreLock(this.lockPath, () => {
+            this.refreshUnderLock();
+            const current = this.index.get(assetId);
+            if (current && (current.trusted === true || current.decision !== undefined))
+                return current;
+            return this.appendUnderLock({
+                assetId,
+                source,
+                trusted: false,
+                at: new Date(this.now()).toISOString(),
+            });
+        });
+    }
+    /** Stage an unverified write without overwriting an explicit trust decision or another conservative marker. */
+    stageUnverifiedWrite(assetId, source, frozenContentId) {
+        return this.stageUnverifiedWriteTracked(assetId, source, frozenContentId).record;
+    }
+    stageUnverifiedWriteTracked(assetId, source, frozenContentId) {
+        assertAssetStoreDirectory(dirname(this.path));
+        return withAssetStoreLock(this.lockPath, () => {
+            this.refreshUnderLock();
+            const current = this.index.get(assetId);
+            const isUndecidedUntrusted = current?.trusted === false
+                && current.decision === undefined
+                && current.decidedBy === undefined
+                && current.promotedBy === undefined;
+            const isWaiver = isUndecidedUntrusted
+                && current.frozenContentId === frozenContentId
+                && ((current.source === 'hub'
+                    && (current.reason === 'unverified_hub_rewrite' || current.reason === 'unverified_hub_synthesized'))
+                    || (current.source === 'migrated' && current.reason === 'unverified_gepx_import'));
+            const isStaleIngestMarker = isUndecidedUntrusted
+                && current.source === source
+                && current.reason === undefined;
+            if (current && !isWaiver && !isStaleIngestMarker)
+                return { record: current, appended: false };
+            return {
+                record: this.appendUnderLock({
+                    assetId,
+                    source,
+                    trusted: false,
+                    reason: 'unverified_hub_write_pending',
+                    frozenContentId,
+                    at: new Date(this.now()).toISOString(),
+                }),
+                appended: true,
+            };
+        });
+    }
+    /** Atomically replace only a pending/no decision with the health-waiver reason after verified persistence. */
+    finalizeUnverifiedWrite(assetId, source, reason, frozenContentId) {
+        assertAssetStoreDirectory(dirname(this.path));
+        return withAssetStoreLock(this.lockPath, () => {
+            this.refreshUnderLock();
+            const current = this.index.get(assetId);
+            if (current) {
+                if (current.trusted === true
+                    || current.decision !== undefined
+                    || current.decidedBy !== undefined
+                    || current.promotedBy !== undefined)
+                    return current;
+                const sameWaiver = current.source === source && current.trusted === false && current.reason === reason;
+                if (sameWaiver && current.frozenContentId === frozenContentId)
+                    return current;
+                if (!sameWaiver && (current.reason !== 'unverified_hub_write_pending'
+                    || (current.frozenContentId !== undefined
+                        && current.frozenContentId !== frozenContentId)))
+                    return current;
+            }
+            return this.appendUnderLock({
+                assetId,
+                source,
+                trusted: false,
+                reason,
+                frozenContentId,
+                at: new Date(this.now()).toISOString(),
+            });
+        });
+    }
     rollbackLast(rec) {
         const line = `${JSON.stringify(rec)}\n`;
         try {
@@ -103,14 +218,22 @@ export class ProvenanceStore {
         return withAssetStoreLock(this.lockPath, () => {
             this.refreshUnderLock();
             const current = this.index.get(assetId) ?? null;
-            if (current?.trusted === trusted)
+            if (trusted
+                && current?.trusted === false
+                && current.decision === undefined
+                && current.reason === 'unverified_hub_write_pending') {
+                throw new ProvenanceWritePendingError(assetId);
+            }
+            const decision = trusted ? 'promoted' : 'revoked';
+            if (current?.trusted === trusted && current.decision === decision) {
                 return { changed: false, record: current };
+            }
             const full = {
                 assetId,
                 source: current?.source ?? 'local',
                 trusted,
                 at: new Date(this.now()).toISOString(),
-                decision: trusted ? 'promoted' : 'revoked',
+                decision,
                 decidedBy: by,
                 ...(trusted ? { promotedBy: by } : {}),
                 reason,
@@ -163,12 +286,82 @@ export async function ingestUnverified(store, prov, record, reason, source = 'hu
     // putFrozen bypasses normalizeForPut, so re-assert the M3-4 Capsule↔gene binding here — a hash-mismatched
     // Capsule with an empty gene must still fail closed on the frozen path, exactly as it does on the verified one.
     assertCapsuleGeneBinding(record);
-    const mark = prov.mark({ assetId: record.asset_id, source, trusted: false, reason });
-    const result = await store.putFrozen(record);
-    // Mirror ingestUntrusted: only an explicit no-write result (dedup) is safe to roll the marker back; a
-    // thrown write has an ambiguous on-disk outcome and must keep the untrusted marker.
-    if (!result.stored)
-        prov.rollbackLast(mark);
+    const frozenContentId = computeAssetId(record);
+    if (!frozenContentId)
+        throw new Error('failed to compute frozen content id');
+    const existing = await store.get(record.asset_id);
+    if (existing) {
+        if (!frozenAssetRecordsEqual(existing, record))
+            throw new FrozenAssetIdCollisionError(record.asset_id);
+        prov.finalizeUnverifiedWrite(record.asset_id, source, reason, frozenContentId);
+        return { asset_id: record.asset_id, stored: false, verified: false };
+    }
+    // Stage a non-waiver record before the body write. If the provider throws or lies about persistence,
+    // the asset stays untrusted and health still reports its hash mismatch instead of treating it as #570.
+    const staged = prov.stageUnverifiedWrite(record.asset_id, source, frozenContentId);
+    // A missing body with an explicit trust decision cannot be replaced without reopening a promotion race.
+    if (staged.source !== source
+        || staged.trusted
+        || staged.decision !== undefined
+        || staged.decidedBy !== undefined
+        || staged.promotedBy !== undefined
+        || staged.reason !== 'unverified_hub_write_pending'
+        || staged.frozenContentId !== frozenContentId) {
+        throw new FrozenAssetIdCollisionError(record.asset_id);
+    }
+    const result = validateFrozenPutResult(await store.putFrozen(record), record.asset_id);
+    const persisted = await store.get(record.asset_id);
+    if (!persisted || !frozenAssetRecordsEqual(persisted, record)) {
+        throw new FrozenAssetIdCollisionError(record.asset_id);
+    }
+    prov.finalizeUnverifiedWrite(record.asset_id, source, reason, frozenContentId);
+    return result;
+}
+/** Atomic frozen variant used by reuse so the logical-id check and append share one provider lock. */
+export async function ingestUnverifiedConditional(store, prov, record, reason, options, source = 'hub') {
+    if (!supportsAtomicFrozenConditionalPut(store)) {
+        throw new Error('asset store does not support conditional frozen writes');
+    }
+    assertCapsuleGeneBinding(record);
+    const frozenContentId = computeAssetId(record);
+    if (!frozenContentId)
+        throw new Error('failed to compute frozen content id');
+    const existing = await store.get(record.asset_id);
+    if (existing) {
+        if (!frozenAssetRecordsEqual(existing, record))
+            throw new FrozenAssetIdCollisionError(record.asset_id);
+        prov.finalizeUnverifiedWrite(record.asset_id, source, reason, frozenContentId);
+        return { asset_id: record.asset_id, stored: false, verified: false, status: 'already_exists' };
+    }
+    const stage = prov.stageUnverifiedWriteTracked(record.asset_id, source, frozenContentId);
+    if (stage.record.source !== source
+        || stage.record.trusted
+        || stage.record.decision !== undefined
+        || stage.record.decidedBy !== undefined
+        || stage.record.promotedBy !== undefined
+        || stage.record.reason !== 'unverified_hub_write_pending'
+        || stage.record.frozenContentId !== frozenContentId) {
+        throw new FrozenAssetIdCollisionError(record.asset_id);
+    }
+    const result = validateConditionalPutResult(await store.putFrozenConditional(record, options), record.asset_id, options);
+    if (result.verified !== false)
+        throw new InvalidFrozenPutResultError();
+    if (!result.stored) {
+        // The pending row may be shared with a concurrent writer. Keep it until a persisted body is finalized.
+        if (result.status === 'already_exists') {
+            const persisted = await store.get(record.asset_id);
+            if (!persisted || !frozenAssetRecordsEqual(persisted, record)) {
+                throw new FrozenAssetIdCollisionError(record.asset_id);
+            }
+            prov.finalizeUnverifiedWrite(record.asset_id, source, reason, frozenContentId);
+        }
+        return result;
+    }
+    const persisted = await store.get(record.asset_id);
+    if (!persisted || !frozenAssetRecordsEqual(persisted, record)) {
+        throw new FrozenAssetIdCollisionError(record.asset_id);
+    }
+    prov.finalizeUnverifiedWrite(record.asset_id, source, reason, frozenContentId);
     return result;
 }
 /**
@@ -180,9 +373,23 @@ export async function ingestUntrustedConditional(store, prov, record, options, s
         throw new Error('asset store does not support conditional writes');
     }
     const normalized = normalizeForPut(record);
-    const mark = prov.mark({ assetId: normalized.record.asset_id, source, trusted: false });
+    const stage = prov.stageUntrustedWriteTracked(normalized.record.asset_id, source);
     const result = validateConditionalPutResult(await store.putConditional(record, options), normalized.record.asset_id, options);
-    if (!result.stored)
-        prov.rollbackLast(mark);
+    if (result.status === 'logical_collision') {
+        if (stage.appended)
+            prov.rollbackLast(stage.record);
+        return result;
+    }
+    if (!result.stored) {
+        const persisted = await store.get(normalized.record.asset_id);
+        if (!persisted || !frozenAssetRecordsEqual(persisted, normalized.record)) {
+            throw new FrozenAssetIdCollisionError(normalized.record.asset_id);
+        }
+        if (stage.appended)
+            prov.rollbackLast(stage.record);
+    }
+    if (!stage.appended) {
+        prov.finalizeUntrustedWrite(normalized.record.asset_id, source);
+    }
     return result;
 }

package/dist/assetstore/provider.d.ts

@@ -10,6 +10,17 @@ export interface PutResult {
     stored: boolean;
     verified: boolean;
 }
+export declare class FrozenAssetIdCollisionError extends Error {
+    readonly assetId: string;
+    readonly code = "FROZEN_ASSET_ID_COLLISION";
+    constructor(assetId: string);
+}
+export declare class InvalidFrozenPutResultError extends Error {
+    readonly code = "INVALID_FROZEN_PUT_RESULT";
+    constructor();
+}
+export declare function frozenAssetRecordsEqual(left: AssetRecord, right: AssetRecord): boolean;
+export declare function validateFrozenPutResult(value: unknown, expectedAssetId: string): PutResult;
 export type ConditionalPutStatus = 'stored' | 'already_exists' | 'logical_collision';
 export interface ConditionalPutOptions {
     /** Only explicit force-like callers may keep multiple content versions for the same type + logical id. */
@@ -34,6 +45,8 @@ export interface SearchQuery {
     category?: string;
     gene?: string;
     text?: string;
+    /** Task-domain scope (hub taxonomy slug, e.g. "software_engineering"). Local providers may ignore it; the hub applies it as a recall fence. */
+    domain?: string;
     limit?: number;
 }
 /**
@@ -46,7 +59,7 @@ export interface AssetStoreProvider {
     putConditional?(asset: AssetRecord, options?: ConditionalPutOptions): Promise<ConditionalPutResult>;
     get(assetId: string): Promise<AssetRecord | null>;
     /** Optional direct lookup for non-content-addressed logical ids. Callers must handle 0, 1, or multiple matches. */
-    findByLogicalId?(id: string, limit?: number): Promise<AssetRecord[]>;
+    findByLogicalId?(id: string, limit?: number, kind?: AssetKind): Promise<AssetRecord[]>;
     /**
      * Optional frozen write: store the record under its OWN declared asset_id without recomputing or
      * normalizing it (bypasses {@link normalizeForPut}'s self-consistency check). Only providers backing a
@@ -55,6 +68,8 @@ export interface AssetStoreProvider {
      * feature-detect it rather than assuming it exists.
      */
     putFrozen?(record: AssetRecord): Promise<PutResult>;
+    /** Atomic frozen variant that also enforces the type + logical-id condition under the provider write lock. */
+    putFrozenConditional?(record: AssetRecord, options?: ConditionalPutOptions): Promise<ConditionalPutResult>;
     search(query: SearchQuery): Promise<AssetRecord[]>;
     list(kind?: AssetKind, limit?: number): Promise<AssetRecord[]>;
 }
@@ -62,6 +77,10 @@ export type AtomicConditionalPutProvider = AssetStoreProvider & {
     putConditional(asset: AssetRecord, options?: ConditionalPutOptions): Promise<ConditionalPutResult>;
 };
 export declare function supportsAtomicConditionalPut(provider: AssetStoreProvider): provider is AtomicConditionalPutProvider;
+export type AtomicFrozenConditionalPutProvider = AssetStoreProvider & {
+    putFrozenConditional(record: AssetRecord, options?: ConditionalPutOptions): Promise<ConditionalPutResult>;
+};
+export declare function supportsAtomicFrozenConditionalPut(provider: AssetStoreProvider): provider is AtomicFrozenConditionalPutProvider;
 export declare class AssetIdMismatchError extends Error {
     readonly claimed: string;
     readonly actual: string;

package/dist/assetstore/provider.js

@@ -1,4 +1,34 @@
-import { computeAssetId, verifyAssetId } from '../wire/index.js';
+import { canonicalize, computeAssetId, verifyAssetId } from '../wire/index.js';
+export class FrozenAssetIdCollisionError extends Error {
+    assetId;
+    code = 'FROZEN_ASSET_ID_COLLISION';
+    constructor(assetId) {
+        super('frozen asset_id already exists with different content');
+        this.assetId = assetId;
+        this.name = 'FrozenAssetIdCollisionError';
+    }
+}
+export class InvalidFrozenPutResultError extends Error {
+    code = 'INVALID_FROZEN_PUT_RESULT';
+    constructor() {
+        super('invalid frozen put result');
+        this.name = 'InvalidFrozenPutResultError';
+    }
+}
+export function frozenAssetRecordsEqual(left, right) {
+    return canonicalize(left) === canonicalize(right);
+}
+export function validateFrozenPutResult(value, expectedAssetId) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new InvalidFrozenPutResultError();
+    const result = value;
+    if (result['asset_id'] !== expectedAssetId
+        || typeof result['stored'] !== 'boolean'
+        || result['verified'] !== false) {
+        throw new InvalidFrozenPutResultError();
+    }
+    return value;
+}
 export class InvalidConditionalPutResultError extends Error {
     reason;
     code = 'INVALID_CONDITIONAL_PUT_RESULT';
@@ -49,6 +79,9 @@ export function validateConditionalPutResult(value, expectedAssetId, options) {
 export function supportsAtomicConditionalPut(provider) {
     return typeof provider.putConditional === 'function';
 }
+export function supportsAtomicFrozenConditionalPut(provider) {
+    return typeof provider.putFrozenConditional === 'function';
+}
 export class AssetIdMismatchError extends Error {
     claimed;
     actual;

package/dist/bootstrap/index.d.ts

@@ -1,2 +1,3 @@
 export * from './selfEvolve.js';
-export * from './envFingerprint.js';
+export * from './envFingerprint.js';
+export * from './v1EnvCompat.js';

package/dist/bootstrap/index.js

@@ -1,2 +1,3 @@
 export * from './selfEvolve.js';
-export * from './envFingerprint.js';
+export * from './envFingerprint.js';
+export * from './v1EnvCompat.js';

package/dist/bootstrap/v1EnvCompat.d.ts

@@ -0,0 +1,110 @@
+/**
+ * V1 → V2 environment variable compatibility layer (#698).
+ *
+ * Evolver V1 used several env var names that are no longer recognized by V2
+ * resolvers. When operators upgrade from V1 to V2 without updating their env
+ * files, these legacy names silently do nothing. This module detects the
+ * presence of deprecated V1 env vars and emits structured warnings so
+ * operators know which knobs to migrate.
+ *
+ * ## Migration map
+ *
+ * | V1 name | V2 equivalent | Notes |
+ * |---|---|---|
+ * | `OPENCLAW_WORKSPACE` | *(manual)* | Partial V2 support does not preserve V1 workspace and bridge semantics |
+ * | `EVOLVER_NO_PARENT_GIT` | *(none)* | V2 uses `EVOLVER_REPO_ROOT` or nearest Git root |
+ * | `EVOLVER_VERBOSE` | *(none)* | V2 has no global switch; opt in to feature-specific diagnostics manually |
+ * | `EVOLVER_AUTO_ISSUE` | *(none)* | V2 creates local drafts; submit requires explicit approval-gated flow |
+ * | `EVOLVER_ROLLBACK_MODE` | *(none)* | V2 uses worktree/snapshot/recovery policy |
+ * | `WORKER_ENABLED` | *(none)* | No merchant-worker resolver in V2 |
+ * | `WORKER_DOMAINS` | *(none)* | No merchant-worker resolver in V2 |
+ * | `WORKER_MAX_LOAD` | *(none)* | No merchant-worker resolver in V2 |
+ * | `EVOLVER_MEMORY_GRAPH_AUTO_ROTATE` | *(none)* | V2 LocalMemoryGraph always performs bounded maintenance |
+ * | `EVOLVER_MEMORY_GRAPH_MAX_SIZE_MB` | *(none)* | V2 LocalMemoryGraph uses a fixed 4 MiB active-file limit |
+ * | `EVOLVER_MEMORY_GRAPH_RETENTION_COUNT` | *(none)* | V2 LocalMemoryGraph retains three archives by default |
+ * | `GITHUB_TOKEN` | `GITHUB_TOKEN` | Already supported by V2 issue reporter and PR tooling |
+ *
+ * GITHUB_TOKEN is NOT deprecated — it's actively used. We only note its
+ * presence for observability.
+ */
+export type V1EnvMigrationAction = 'map' | 'manual' | 'remove';
+/** Metadata for a single V1 env var deprecation entry. */
+export interface V1EnvDeprecation {
+    /** The deprecated V1 env var name. */
+    readonly v1Name: string;
+    /** The V2 equivalent, or `null` if no equivalent exists. */
+    readonly v2Equivalent: string | null;
+    /** Whether migration is an exact map, requires operator review, or only removes the V1 key. */
+    readonly migrationAction?: V1EnvMigrationAction;
+    /** Human-readable migration guidance. */
+    readonly guidance: string;
+}
+/** Result of scanning for deprecated V1 env vars. */
+export interface V1EnvCompatResult {
+    /** Deprecated V1 vars that were found set (non-empty) in the environment. */
+    readonly detected: V1EnvDeprecation[];
+    /** `GITHUB_TOKEN` or `GH_TOKEN` presence flag (not deprecated, just noted). */
+    readonly githubTokenPresent: boolean;
+}
+/**
+ * The canonical table of V1 → V2 env var deprecations.
+ *
+ * Order matters for deterministic output; the scan iterates this list
+ * and checks each entry against the provided `env` object.
+ */
+export declare const V1_DEPRECATION_TABLE: readonly V1EnvDeprecation[];
+/**
+ * Scan the provided environment for deprecated V1 env vars and return
+ * structured results. This function is purely read-only and never mutates
+ * the `env` object.
+ *
+ * @param env  The environment to scan (defaults to `process.env`).
+ * @returns    Structured scan results including detected deprecations.
+ */
+export declare function scanV1EnvCompat(env?: Record<string, string | undefined>): V1EnvCompatResult;
+/** Resolve the migration action while preserving compatibility with pre-action table entries. */
+export declare function resolveV1EnvMigrationAction(entry: Pick<V1EnvDeprecation, 'migrationAction' | 'v2Equivalent'>): V1EnvMigrationAction;
+/**
+ * Emit deprecation warnings to the provided logger for all detected
+ * deprecated V1 env vars. This is the primary integration point for
+ * entrypoints that want human-readable console output.
+ *
+ * @param result  The scan result from `scanV1EnvCompat`.
+ * @param warn    Logger function (defaults to `console.warn`).
+ */
+export declare function emitV1DeprecationWarnings(result: V1EnvCompatResult, warn?: (msg: string) => void): void;
+/**
+ * Convenience function: scan + emit in one call. Intended for early
+ * bootstrap in CLI/proxy/MCP entrypoints.
+ *
+ * @param env  The environment to scan.
+ * @param warn Logger function.
+ * @returns    The scan result (useful for programmatic inspection).
+ */
+export declare function checkV1EnvCompat(env?: Record<string, string | undefined>, warn?: (msg: string) => void): V1EnvCompatResult;
+/** One suggested V2 assignment produced from a V1 env map. */
+export interface V1EnvTranslationSuggestion {
+    readonly v1Name: string;
+    readonly action: V1EnvMigrationAction | 'keep';
+    readonly v2Name?: string;
+    readonly v2Value?: string;
+    readonly guidance: string;
+}
+/** Full offline translation report for migrate env / doctor. */
+export interface V1EnvTranslationReport {
+    readonly suggestions: V1EnvTranslationSuggestion[];
+    readonly detectedCount: number;
+    readonly mappableCount: number;
+    readonly manualCount: number;
+    readonly removableCount: number;
+    readonly githubTokenPresent: boolean;
+}
+/**
+ * Build an offline V1→V2 env translation report.
+ * Does not write files; callers decide how to present or apply suggestions.
+ * Raw values are retained only as v2Value for mappable non-secret keys.
+ * GITHUB_TOKEN and GH_TOKEN are reported as keep without retaining their values.
+ */
+export declare function translateV1Env(env?: Record<string, string | undefined>): V1EnvTranslationReport;
+/** Human-readable report (never prints secret-looking values; only key names + actions). */
+export declare function formatV1EnvTranslationReport(report: V1EnvTranslationReport): string;