synergyspec-selfevolving 1.3.0 → 2.0.0

package/dist/core/self-evolution/policy/fs-safe.js

@@ -0,0 +1,89 @@
+/**
+ * Filesystem safety primitives shared by candidate promotion (`promote.ts`)
+ * and the 策略 POLICY module（版本账本 + 否决缓冲）. Extracted from `promote.ts`
+ * unchanged so both write paths go through the SAME fail-closed helpers:
+ * never write outside the repo root, and never leave a half-written file
+ * behind (sibling tmp + rename).
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+/** Throw if `abs` resolves outside `repoRoot`. */
+export function assertWithinRepo(repoRoot, abs) {
+    const base = path.resolve(repoRoot);
+    const target = path.resolve(abs);
+    const rel = path.relative(base, target);
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+        throw new Error(`Refusing to write outside repo root. root=${base} target=${target}`);
+    }
+}
+/**
+ * fsync a single path best-effort: open it, `fdatasync`/`fsync`, close. Swallows
+ * EISDIR/EPERM/EINVAL/ENOSYS so a host (notably Windows) that refuses to fsync a
+ * directory handle does not turn a durability hardening into a hard failure. The
+ * caller's data is already on disk via the rename; this only pushes it past the
+ * OS write cache so a crash cannot lose it.
+ */
+async function fsyncPathBestEffort(target) {
+    let handle;
+    try {
+        handle = await fs.open(target, 'r');
+        await handle.sync();
+    }
+    catch (err) {
+        const code = err.code;
+        // Windows dir fsync (and some filesystems) reject the operation — best-effort.
+        if (code !== 'EISDIR' && code !== 'EPERM' && code !== 'EINVAL' && code !== 'ENOSYS') {
+            // Non-fatal even otherwise: durability is a hardening, not a correctness gate.
+        }
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+}
+/**
+ * Atomic write via sibling tmp file + rename; cleans up on rename failure. After
+ * the rename, fsync the file and (best-effort) its parent directory so a host
+ * crash cannot lose a just-renamed record a later separate process relies on —
+ * the rename is only durable once the directory entry itself is flushed.
+ */
+export async function writeFileAtomic(abs, content) {
+    const dir = path.dirname(abs);
+    const tmp = path.join(dir, `.${path.basename(abs)}.tmp-${crypto.randomBytes(4).toString('hex')}`);
+    await fs.writeFile(tmp, content, 'utf8');
+    try {
+        await fs.rename(tmp, abs);
+    }
+    catch (err) {
+        try {
+            await fs.rm(tmp, { force: true });
+        }
+        catch {
+            // ignore
+        }
+        throw err;
+    }
+    // Durability: flush the renamed file, then the parent dir entry (dir fsync may
+    // throw on Windows — guarded inside fsyncPathBestEffort). Both best-effort.
+    await fsyncPathBestEffort(abs);
+    await fsyncPathBestEffort(dir);
+}
+/**
+ * Append `content` to a file and fsync the file descriptor so a host crash
+ * cannot lose the just-appended record. Used by the append-only stores (the
+ * 版本账本 ledger and the 否决缓冲 reject-buffer): a later SEPARATE process
+ * (`resumeEpisode`) relies on these records being durable, so the OS write cache
+ * must be flushed before we return. Does NOT change the bytes written (one
+ * `append` of `content`); only adds the fsync. Byte content is the caller's.
+ */
+export async function appendFileDurable(abs, content) {
+    const handle = await fs.open(abs, 'a');
+    try {
+        await handle.appendFile(content, 'utf8');
+        await handle.sync();
+    }
+    finally {
+        await handle.close().catch(() => { });
+    }
+}
+//# sourceMappingURL=fs-safe.js.map

package/dist/core/self-evolution/policy/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 策略 POLICY module（版本账本 + 否决缓冲）— sub-barrel.
+ *
+ * The policy is the design template（主智能体的「权重」）living in the user's
+ * repo; the CLI 持有版本 (holds the VERSION): `policy-store.ts` keeps the
+ * 版本账本 ledger + snapshots + one-in-flight lock, `reject-buffer.ts` keeps
+ * the 否决缓冲, and `fs-safe.ts` holds the fail-closed write primitives
+ * shared with `promote.ts`.
+ */
+export * from './fs-safe.js';
+export * from './policy-store.js';
+export * from './reject-buffer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/self-evolution/policy/index.js

@@ -0,0 +1,13 @@
+/**
+ * 策略 POLICY module（版本账本 + 否决缓冲）— sub-barrel.
+ *
+ * The policy is the design template（主智能体的「权重」）living in the user's
+ * repo; the CLI 持有版本 (holds the VERSION): `policy-store.ts` keeps the
+ * 版本账本 ledger + snapshots + one-in-flight lock, `reject-buffer.ts` keeps
+ * the 否决缓冲, and `fs-safe.ts` holds the fail-closed write primitives
+ * shared with `promote.ts`.
+ */
+export * from './fs-safe.js';
+export * from './policy-store.js';
+export * from './reject-buffer.js';
+//# sourceMappingURL=index.js.map

package/dist/core/self-evolution/policy/policy-store.d.ts

@@ -0,0 +1,217 @@
+export declare const POLICY_LEDGER_FILE = "ledger.ndjson";
+export declare const POLICY_IN_FLIGHT_FILE = "in-flight.json";
+export declare const POLICY_REJECT_BUFFER_FILE = "reject-buffer.ndjson";
+export declare const POLICY_SNAPSHOT_MANIFEST_FILE = "manifest.json";
+export declare const POLICY_SNAPSHOT_FILES_DIR = "files";
+export declare const POLICY_SNAPSHOT_DELTA_FILE = "delta.patch";
+/** An in-flight episode older than this is stale and its slot reclaimable. */
+export declare const IN_FLIGHT_STALE_MS: number;
+/** What a ledger entry records happened to the lineage. */
+export type PolicyLedgerAction = 'init' | 'evolve' | 'rollback' | 'refused';
+/** One file the policy version covers, content-addressed for verification. */
+export interface PolicyLedgerFileEntry {
+    /** Repo-relative POSIX path of the live policy file. */
+    relPath: string;
+    /** SHA-256 (hex) of the file's bytes at this version. */
+    sha256: string;
+}
+/**
+ * The falsifiable bet attached to an 'evolve' step: which scoreboard metric
+ * the edit is predicted to move, in which direction, and by when the
+ * prediction is checkable (so a later episode can settle it).
+ */
+export interface PolicyPrediction {
+    metric: 'loss' | 'passRate' | 'healthPenalty';
+    direction: 'down' | 'up';
+    checkBy: string;
+}
+/** Size of an 'evolve'/'rollback' step, derived from its `delta.patch`. */
+export interface PolicyDeltaStats {
+    filesChanged: number;
+    linesAdded: number;
+    linesRemoved: number;
+}
+/** One line of the 版本账本 ledger (`ledger.ndjson`). */
+export interface PolicyLedgerEntry {
+    schemaVersion: 1;
+    version: number;
+    targetId: string;
+    /** ISO-8601 UTC timestamp. */
+    at: string;
+    action: PolicyLedgerAction;
+    /** `null` only for 'init' (no episode owns lineage creation). */
+    episodeId: string | null;
+    files: PolicyLedgerFileEntry[];
+    prediction?: PolicyPrediction;
+    /** advantage ＝ reward(主臂) − reward(基线臂), when one was measured. */
+    advantage?: number;
+    deltaStats?: PolicyDeltaStats;
+    /** Why the 演进智能体 EVOLVING AGENT refused ('refused' entries only). */
+    reason?: string;
+}
+/** `manifest.json` inside one `snapshots/<target-id-slug>/v<N>/` dir. */
+export interface PolicySnapshotManifest {
+    version: number;
+    targetId: string;
+    at: string;
+    files: PolicyLedgerFileEntry[];
+}
+/** One in-flight episode for one target (`in-flight.json` value). */
+export interface PolicyInFlightEntry {
+    targetId: string;
+    episodeId: string;
+    /** The lineage head version when the episode started. */
+    sinceVersion: number;
+    /** ISO-8601 UTC timestamp; staleness is measured from here. */
+    startedAt: string;
+}
+/** Resolved on-disk paths of the policy dir. No I/O is performed. */
+export interface PolicyLayout {
+    repoRoot: string;
+    /** `<repoRoot>/.synergyspec-selfevolving/self-evolution/policy`. */
+    baseDir: string;
+    ledgerPath: string;
+    snapshotsDir: string;
+    inFlightPath: string;
+    rejectBufferPath: string;
+}
+/** Compute the policy dir layout for a repo. */
+export declare function resolvePolicyLayout(repoRoot: string): PolicyLayout;
+/** Kebab-case a target id for use as a snapshot directory name. */
+export declare function targetIdSlug(targetId: string): string;
+/** Absolute path of one version's snapshot dir. No I/O is performed. */
+export declare function policySnapshotDir(layout: PolicyLayout, targetId: string, version: number): string;
+/**
+ * Read one target's slice of the 版本账本 ledger, in append order. Returns
+ * `[]` when the ledger does not exist. Malformed/blank lines are skipped
+ * best-effort (forward-compatible, matching the repo's other ndjson readers).
+ */
+export declare function readPolicyLedger(repoRoot: string, targetId: string): Promise<PolicyLedgerEntry[]>;
+/**
+ * Read the ENTIRE 版本账本 ledger across all targets, in append order. Returns
+ * `[]` when the ledger does not exist. Malformed/blank lines are skipped
+ * best-effort (forward-compatible, matching the repo's other ndjson readers).
+ */
+export declare function readPolicyLedgerAll(repoRoot: string): Promise<PolicyLedgerEntry[]>;
+/**
+ * The lineage head version for a target, or `null` when the lineage has not
+ * been initialized. The 单一血统 single lineage is append-only, so the head is
+ * simply the LAST ledger entry's version ('refused' entries carry the
+ * unchanged head; 'evolve'/'rollback' carry the new one).
+ */
+export declare function currentPolicyVersion(repoRoot: string, targetId: string): Promise<number | null>;
+/**
+ * Read one version's snapshotted files (byte-for-byte). Verifies every file
+ * against the manifest's sha256 and throws on a mismatch — a snapshot is the
+ * restore source of truth, so corruption is a hard error, never silent.
+ */
+export declare function readPolicySnapshotFiles(repoRoot: string, targetId: string, version: number): Promise<{
+    relPath: string;
+    content: string;
+}[]>;
+/**
+ * Shape of the injectable resolver seam: the slice of
+ * {@link resolveTargetLocalFiles}'s result that init actually reads.
+ */
+export type PolicyResolveFiles = (targetId: string, repoRoot: string) => Promise<{
+    files: {
+        relPath: string;
+        content: string;
+    }[];
+}>;
+export interface InitPolicyLineageOptions {
+    repoRoot: string;
+    targetId: string;
+    /** TEST seam. Defaults to the real {@link resolveTargetLocalFiles}. */
+    resolveFiles?: PolicyResolveFiles;
+}
+/**
+ * Start a target's 单一血统 single lineage: snapshot v0 of the target's
+ * CURRENT resolved local files and append the 'init' ledger entry. Refuses to
+ * re-init an existing lineage (the version axis never restarts).
+ */
+export declare function initPolicyLineage(opts: InitPolicyLineageOptions): Promise<PolicyLedgerEntry>;
+export interface AdvancePolicyVersionOptions {
+    repoRoot: string;
+    targetId: string;
+    episodeId: string;
+    /** Full new contents for the edited lineage file(s). */
+    edits: {
+        relPath: string;
+        content: string;
+    }[];
+    prediction: PolicyPrediction;
+}
+/**
+ * Apply the 演进智能体 EVOLVING AGENT's ONE bounded edit as the next policy
+ * version. 单一血统 single-lineage enforcement: the live files must still be
+ * byte-identical to the lineage head snapshot — if anything advanced or edited
+ * them out-of-band, the head is not the expected base and this throws (roll
+ * back, or re-init, before evolving again).
+ *
+ * Order is snapshot-then-write: the NEW version's snapshot dir is committed
+ * first, then the live files are written atomically; a mid-write failure
+ * restores every live file from the head content and discards the new
+ * snapshot before rethrowing. The 'evolve' ledger entry (with `prediction`
+ * and `deltaStats`) is appended only after every live write succeeded.
+ */
+export declare function advancePolicyVersion(opts: AdvancePolicyVersionOptions): Promise<PolicyLedgerEntry>;
+export interface RollbackPolicyVersionOptions {
+    repoRoot: string;
+    targetId: string;
+    episodeId: string;
+    toVersion: number;
+    /** The measured (bad) advantage that triggered the rollback, when known. */
+    advantage?: number;
+}
+/**
+ * Restore the live policy files byte-for-byte from snapshot v<toVersion> and
+ * append a 'rollback' ledger entry. The restore is recorded as a NEW head
+ * version whose files equal the old snapshot (git-revert style) so the
+ * 单一血统 single lineage stays monotonic — the version axis never rewinds.
+ * Unlike advance, rollback does NOT require the live files to match the head:
+ * it is the recovery path, including for out-of-band live-file divergence.
+ */
+export declare function rollbackPolicyVersion(opts: RollbackPolicyVersionOptions): Promise<PolicyLedgerEntry>;
+export interface RecordEvolutionRefusedOptions {
+    repoRoot: string;
+    targetId: string;
+    episodeId: string;
+    reason: string;
+}
+/**
+ * Record an episode where the 演进智能体 EVOLVING AGENT refused to edit. The
+ * version does NOT bump (vN+1 ≡ vN) — this entry is exactly what the
+ * CRITIC AGENT（基线智能体 baseline agent）'s skip condition reads: the policy
+ * is unchanged, so rerunning the baseline arm would compare a policy against
+ * itself. No files are touched.
+ */
+export declare function recordEvolutionRefused(opts: RecordEvolutionRefusedOptions): Promise<PolicyLedgerEntry>;
+export interface AcquireInFlightOptions {
+    repoRoot: string;
+    targetId: string;
+    episodeId: string;
+    /** Injectable clock for tests; defaults to `new Date()`. */
+    now?: Date;
+}
+/**
+ * Claim the one in-flight slot for a target. Throws while a NON-stale entry
+ * exists for the target (one in-flight per target); an entry whose
+ * `startedAt` is ≥ {@link IN_FLIGHT_STALE_MS} old is stale and its slot is
+ * reclaimed (the abandoned episode's worktree is 产物即弃 — worktree
+ * artifacts discarded). Records `sinceVersion` = the lineage head at acquire
+ * time, so the episode knows which policy version it started from.
+ */
+export declare function acquireInFlight(opts: AcquireInFlightOptions): Promise<PolicyInFlightEntry>;
+export interface ReleaseInFlightOptions {
+    repoRoot: string;
+    targetId: string;
+    episodeId: string;
+}
+/**
+ * Release a target's in-flight slot. Idempotent when no entry exists; throws
+ * when the slot is held by a DIFFERENT episode (an episode may only release
+ * its own claim).
+ */
+export declare function releaseInFlight(opts: ReleaseInFlightOptions): Promise<void>;
+//# sourceMappingURL=policy-store.d.ts.map