@vauban-org/agent-sdk 0.17.4 → 1.2.0

package/dist/skill-loop/reflexion-replay.js

@@ -0,0 +1,110 @@
+/**
+ * src/skill-loop/reflexion-replay.ts
+ *
+ * Deterministic reflexion storage and replay.
+ *
+ * Invariants:
+ *   - Reflexion is stored as a deterministic hash, NOT an LLM paraphrase.
+ *   - replay() with the same args produces bit-identical output every time.
+ *   - The replay hash is SHA-256(skillId + ":" + domain + ":" + instructionsHash).
+ *   - No LLM calls. Pure deterministic computation.
+ *
+ * @module skill-loop/reflexion-replay
+ */
+import { createHash } from "node:crypto";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function sha256Hex(input) {
+    return createHash("sha256").update(input, "utf8").digest("hex");
+}
+function computeReplayHash(skillId, domain, instructionsHash) {
+    return sha256Hex(`${skillId}:${domain}:${instructionsHash}`);
+}
+// ---------------------------------------------------------------------------
+// ReflexionStore
+// ---------------------------------------------------------------------------
+/**
+ * In-memory deterministic reflexion store.
+ *
+ * In production, persist entries to the DB (table: skill_reflexions).
+ * This implementation is process-local and suitable for tests.
+ */
+export class ReflexionStore {
+    entries = new Map();
+    // ── Store ──────────────────────────────────────────────────────────────────
+    /**
+     * Store a reflexion entry deterministically.
+     *
+     * The replayHash is computed solely from (skillId, domain, instructions) —
+     * no randomness, no timestamps in the hash computation.
+     * Idempotent: storing with the same inputs overwrites with bit-identical data.
+     *
+     * @param skillId      - Skill identifier.
+     * @param domain       - Domain key.
+     * @param instructions - Raw skill instructions (deterministic source).
+     * @param lesson       - Extracted lesson (must be deterministic — NOT LLM output).
+     * @param scores       - Constitutional and outcome scores.
+     * @param nowDate      - Optional timestamp override for testing.
+     */
+    store(skillId, domain, instructions, lesson, scores, nowDate) {
+        const instructionsHash = sha256Hex(instructions);
+        const replayHash = computeReplayHash(skillId, domain, instructionsHash);
+        const entry = {
+            replayHash,
+            skillId,
+            domain,
+            instructionsHash,
+            lesson,
+            scores,
+            storedAt: (nowDate ?? new Date()).toISOString(),
+        };
+        this.entries.set(replayHash, entry);
+        return entry;
+    }
+    // ── Replay ─────────────────────────────────────────────────────────────────
+    /**
+     * Replay a stored reflexion with the same arguments.
+     *
+     * Determinism guarantee: replay(skillId, domain, instructions) with the
+     * same inputs as the original store() call ALWAYS produces the same
+     * replayHash and lesson — bit-identical output.
+     *
+     * @returns ReplayResult with `identical: true` if the entry is found and
+     *          the recomputed hash matches the stored replayHash.
+     */
+    replay(skillId, domain, instructions) {
+        const instructionsHash = sha256Hex(instructions);
+        const replayHash = computeReplayHash(skillId, domain, instructionsHash);
+        const entry = this.entries.get(replayHash);
+        if (!entry)
+            return null;
+        // Verify bit-identical determinism
+        const identical = replayHash === entry.replayHash &&
+            instructionsHash === entry.instructionsHash;
+        return {
+            replayHash,
+            lesson: entry.lesson,
+            scores: entry.scores,
+            identical,
+        };
+    }
+    // ── Queries ────────────────────────────────────────────────────────────────
+    /** Retrieve an entry by its replay hash. */
+    get(replayHash) {
+        return this.entries.get(replayHash) ?? null;
+    }
+    /** List all stored entries for a given skill. */
+    listBySkill(skillId) {
+        return Array.from(this.entries.values()).filter((e) => e.skillId === skillId);
+    }
+    /** Total number of stored entries. */
+    get size() {
+        return this.entries.size;
+    }
+    /** Clear all entries (useful for test isolation). */
+    clear() {
+        this.entries.clear();
+    }
+}
+//# sourceMappingURL=reflexion-replay.js.map

package/dist/skill-loop/reflexion-replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflexion-replay.js","sourceRoot":"","sources":["../../src/skill-loop/reflexion-replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA6BzC,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,SAAS,SAAS,CAAC,KAAa;IAC9B,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAClE,CAAC;AAED,SAAS,iBAAiB,CACxB,OAAe,EACf,MAAc,EACd,gBAAwB;IAExB,OAAO,SAAS,CAAC,GAAG,OAAO,IAAI,MAAM,IAAI,gBAAgB,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,OAAO,cAAc;IACR,OAAO,GAAG,IAAI,GAAG,EAA0B,CAAC;IAE7D,8EAA8E;IAE9E;;;;;;;;;;;;;OAaG;IACH,KAAK,CACH,OAAe,EACf,MAAc,EACd,YAAoB,EACpB,MAAc,EACd,MAAmD,EACnD,OAAc;QAEd,MAAM,gBAAgB,GAAG,SAAS,CAAC,YAAY,CAAC,CAAC;QACjD,MAAM,UAAU,GAAG,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC;QAExE,MAAM,KAAK,GAAmB;YAC5B,UAAU;YACV,OAAO;YACP,MAAM;YACN,gBAAgB;YAChB,MAAM;YACN,MAAM;YACN,QAAQ,EAAE,CAAC,OAAO,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE;SAChD,CAAC;QAEF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QACpC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,8EAA8E;IAE9E;;;;;;;;;OASG;IACH,MAAM,CACJ,OAAe,EACf,MAAc,EACd,YAAoB;QAEpB,MAAM,gBAAgB,GAAG,SAAS,CAAC,YAAY,CAAC,CAAC;QACjD,MAAM,UAAU,GAAG,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC;QAExE,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QAExB,mCAAmC;QACnC,MAAM,SAAS,GACb,UAAU,KAAK,KAAK,CAAC,UAAU;YAC/B,gBAAgB,KAAK,KAAK,CAAC,gBAAgB,CAAC;QAE9C,OAAO;YACL,UAAU;YACV,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,SAAS;SACV,CAAC;IACJ,CAAC;IAED,8EAA8E;IAE9E,4CAA4C;IAC5C,GAAG,CAAC,UAAkB;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC;IAC9C,CAAC;IAED,iDAAiD;IACjD,WAAW,CAAC,OAAe;QACzB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAC7C,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,CAC7B,CAAC;IACJ,CAAC;IAED,sCAAsC;IACtC,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED,qDAAqD;IACrD,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;CACF"}

package/dist/skill-loop/sign-off.d.ts

@@ -0,0 +1,88 @@
+/**
+ * src/skill-loop/sign-off.ts
+ *
+ * Article 14 human oversight mechanism for skill promotion.
+ *
+ * Invariants:
+ *   - Audit trail: { approver_id, timestamp, decision, rationale, signed_hash }
+ *   - signed_hash = SHA-256(candidateId + decision + rationale + isoTimestamp)
+ *   - Escalation: approver unavailable >72h → auto-REJECTED (never auto-approved)
+ *   - Multiple approvers possible; one sign-off is sufficient for promotion.
+ *
+ * @module skill-loop/sign-off
+ */
+export type SignOffDecision = "approved" | "rejected";
+export interface SignOffRecord {
+    /** Candidate ID this sign-off covers. */
+    candidateId: string;
+    /** Identifier of the human approver (e.g. user UUID or username). */
+    approverId: string;
+    /** ISO-8601 timestamp at which the decision was recorded. */
+    timestamp: string;
+    /** Human decision. */
+    decision: SignOffDecision;
+    /** Human-provided rationale (non-empty required). */
+    rationale: string;
+    /**
+     * Integrity hash: SHA-256(candidateId + decision + rationale + timestamp).
+     * Detects tampering in the audit trail.
+     */
+    signedHash: string;
+}
+export interface PendingRequest {
+    candidateId: string;
+    requestedAt: string;
+    /** Approver ID if a specific approver is designated. Null = any approver. */
+    approverId: string | null;
+    /** Deadline beyond which the request is auto-rejected (72h from requestedAt). */
+    deadlineAt: string;
+}
+/**
+ * Manages pending approval requests and sign-off records.
+ *
+ * In production, records should be persisted to the DB. This implementation
+ * is in-memory and suitable for tests and single-process environments.
+ */
+export declare class SignOffManager {
+    private readonly records;
+    private readonly pending;
+    /** 72-hour escalation deadline in milliseconds. */
+    static readonly ESCALATION_DEADLINE_MS: number;
+    /**
+     * Create a pending approval request for a candidate.
+     *
+     * If a request already exists and is not expired, returns the existing one.
+     */
+    requestSignOff(candidateId: string, approverId?: string | null, nowDate?: Date): PendingRequest;
+    /**
+     * Record a sign-off decision (approved or rejected).
+     *
+     * @throws If rationale is empty or candidateId is missing.
+     */
+    recordDecision(candidateId: string, approverId: string, decision: SignOffDecision, rationale: string, nowDate?: Date): SignOffRecord;
+    /**
+     * Check all pending requests and auto-reject any that have exceeded the 72h deadline.
+     *
+     * @returns Array of auto-rejection records created.
+     */
+    escalateExpired(nowDate?: Date): SignOffRecord[];
+    /**
+     * Returns the first approved sign-off for a candidate, or null if none exists.
+     * One sign-off is sufficient for promotion.
+     */
+    getApproval(candidateId: string): SignOffRecord | null;
+    /**
+     * Returns all sign-off records for a candidate (audit trail).
+     */
+    getAuditTrail(candidateId: string): SignOffRecord[];
+    /**
+     * Returns true if a pending request exists and has not expired.
+     */
+    hasPending(candidateId: string, nowDate?: Date): boolean;
+    /**
+     * Verify the integrity of a sign-off record by recomputing its hash.
+     */
+    verifyRecord(record: SignOffRecord): boolean;
+    private isExpired;
+}
+//# sourceMappingURL=sign-off.d.ts.map

package/dist/skill-loop/sign-off.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign-off.d.ts","sourceRoot":"","sources":["../../src/skill-loop/sign-off.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,UAAU,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,QAAQ,EAAE,eAAe,CAAC;IAC1B,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,iFAAiF;IACjF,UAAU,EAAE,MAAM,CAAC;CACpB;AA4BD;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAC9D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAE7D,mDAAmD;IACnD,MAAM,CAAC,QAAQ,CAAC,sBAAsB,SAAwB;IAI9D;;;;OAIG;IACH,cAAc,CACZ,WAAW,EAAE,MAAM,EACnB,UAAU,GAAE,MAAM,GAAG,IAAW,EAChC,OAAO,CAAC,EAAE,IAAI,GACb,cAAc;IAuBjB;;;;OAIG;IACH,cAAc,CACZ,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,eAAe,EACzB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,IAAI,GACb,aAAa;IAoChB;;;;OAIG;IACH,eAAe,CAAC,OAAO,CAAC,EAAE,IAAI,GAAG,aAAa,EAAE;IAqBhD;;;OAGG;IACH,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAStD;;OAEG;IACH,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,EAAE;IAInD;;OAEG;IACH,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,GAAG,OAAO;IAQxD;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO;IAY5C,OAAO,CAAC,SAAS;CAKlB"}

package/dist/skill-loop/sign-off.js

@@ -0,0 +1,146 @@
+/**
+ * src/skill-loop/sign-off.ts
+ *
+ * Article 14 human oversight mechanism for skill promotion.
+ *
+ * Invariants:
+ *   - Audit trail: { approver_id, timestamp, decision, rationale, signed_hash }
+ *   - signed_hash = SHA-256(candidateId + decision + rationale + isoTimestamp)
+ *   - Escalation: approver unavailable >72h → auto-REJECTED (never auto-approved)
+ *   - Multiple approvers possible; one sign-off is sufficient for promotion.
+ *
+ * @module skill-loop/sign-off
+ */
+import { createHash } from "node:crypto";
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function sha256Hex(input) {
+    return createHash("sha256").update(input, "utf8").digest("hex");
+}
+function isoNow(overrideDate) {
+    return (overrideDate ?? new Date()).toISOString();
+}
+/** Compute the signed hash per the canonical formula. */
+function computeSignedHash(candidateId, decision, rationale, timestamp) {
+    return sha256Hex(`${candidateId}${decision}${rationale}${timestamp}`);
+}
+// ---------------------------------------------------------------------------
+// SignOffManager
+// ---------------------------------------------------------------------------
+/**
+ * Manages pending approval requests and sign-off records.
+ *
+ * In production, records should be persisted to the DB. This implementation
+ * is in-memory and suitable for tests and single-process environments.
+ */
+export class SignOffManager {
+    records = new Map();
+    pending = new Map();
+    /** 72-hour escalation deadline in milliseconds. */
+    static ESCALATION_DEADLINE_MS = 72 * 60 * 60 * 1_000;
+    // ── Request ─────────────────────────────────────────────────────────────────
+    /**
+     * Create a pending approval request for a candidate.
+     *
+     * If a request already exists and is not expired, returns the existing one.
+     */
+    requestSignOff(candidateId, approverId = null, nowDate) {
+        const existing = this.pending.get(candidateId);
+        if (existing && !this.isExpired(existing, nowDate)) {
+            return existing;
+        }
+        const requestedAt = isoNow(nowDate);
+        const deadline = new Date((nowDate ?? new Date()).getTime() + SignOffManager.ESCALATION_DEADLINE_MS);
+        const request = {
+            candidateId,
+            requestedAt,
+            approverId,
+            deadlineAt: deadline.toISOString(),
+        };
+        this.pending.set(candidateId, request);
+        return request;
+    }
+    // ── Approve / Reject ────────────────────────────────────────────────────────
+    /**
+     * Record a sign-off decision (approved or rejected).
+     *
+     * @throws If rationale is empty or candidateId is missing.
+     */
+    recordDecision(candidateId, approverId, decision, rationale, nowDate) {
+        if (!rationale || rationale.trim().length === 0) {
+            throw new Error(`sign-off: rationale is required for decision "${decision}" on candidate "${candidateId}"`);
+        }
+        const timestamp = isoNow(nowDate);
+        const signedHash = computeSignedHash(candidateId, decision, rationale, timestamp);
+        const record = {
+            candidateId,
+            approverId,
+            timestamp,
+            decision,
+            rationale,
+            signedHash,
+        };
+        const existing = this.records.get(candidateId) ?? [];
+        existing.push(record);
+        this.records.set(candidateId, existing);
+        // Remove the pending request once a decision is recorded.
+        this.pending.delete(candidateId);
+        return record;
+    }
+    // ── Escalation ──────────────────────────────────────────────────────────────
+    /**
+     * Check all pending requests and auto-reject any that have exceeded the 72h deadline.
+     *
+     * @returns Array of auto-rejection records created.
+     */
+    escalateExpired(nowDate) {
+        const rejections = [];
+        for (const [candidateId, request] of this.pending.entries()) {
+            if (this.isExpired(request, nowDate)) {
+                const record = this.recordDecision(candidateId, "system:escalation", "rejected", "Auto-rejected: approver unavailable >72h (Art. 14 escalation — never auto-approved)", nowDate);
+                rejections.push(record);
+            }
+        }
+        return rejections;
+    }
+    // ── Queries ─────────────────────────────────────────────────────────────────
+    /**
+     * Returns the first approved sign-off for a candidate, or null if none exists.
+     * One sign-off is sufficient for promotion.
+     */
+    getApproval(candidateId) {
+        const records = this.records.get(candidateId) ?? [];
+        return (records.find((r) => r.decision === "approved" && r.approverId !== "system:escalation") ?? null);
+    }
+    /**
+     * Returns all sign-off records for a candidate (audit trail).
+     */
+    getAuditTrail(candidateId) {
+        return this.records.get(candidateId) ?? [];
+    }
+    /**
+     * Returns true if a pending request exists and has not expired.
+     */
+    hasPending(candidateId, nowDate) {
+        const request = this.pending.get(candidateId);
+        if (!request)
+            return false;
+        return !this.isExpired(request, nowDate);
+    }
+    // ── Verification ────────────────────────────────────────────────────────────
+    /**
+     * Verify the integrity of a sign-off record by recomputing its hash.
+     */
+    verifyRecord(record) {
+        const expected = computeSignedHash(record.candidateId, record.decision, record.rationale, record.timestamp);
+        return expected === record.signedHash;
+    }
+    // ── Private ─────────────────────────────────────────────────────────────────
+    isExpired(request, nowDate) {
+        const deadline = new Date(request.deadlineAt).getTime();
+        const now = (nowDate ?? new Date()).getTime();
+        return now > deadline;
+    }
+}
+//# sourceMappingURL=sign-off.js.map

package/dist/skill-loop/sign-off.js.map

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

package/dist/skill-loop/value-metric.d.ts

@@ -0,0 +1,55 @@
+/**
+ * src/skill-loop/value-metric.ts
+ *
+ * skill_value formula: cumulative weekly metric.
+ *
+ *   skill_value = Σ(usage_count × outcome_delta_vs_baseline)
+ *
+ * Consumer provides an outcomeDeltaCalculator function that returns the
+ * outcome delta for a given usage event. The metric is cumulative over a
+ * sliding 7-day window.
+ *
+ * @module skill-loop/value-metric
+ */
+export interface UsageEvent {
+    /** Skill ID this event belongs to. */
+    skillId: string;
+    /** ISO-8601 timestamp of the usage event. */
+    timestamp: string;
+    /** Arbitrary context passed to the outcomeDeltaCalculator. */
+    context: Record<string, unknown>;
+}
+export interface SkillValueResult {
+    skillId: string;
+    /** Sum of (usage × outcome_delta) over the window. */
+    skillValue: number;
+    /** Number of usage events included. */
+    usageCount: number;
+    /** Sum of all individual outcome deltas (raw). */
+    totalOutcomeDelta: number;
+    /** Start of the 7-day window (ISO-8601). */
+    windowStart: string;
+    /** End of the 7-day window (ISO-8601). */
+    windowEnd: string;
+}
+/**
+ * Compute skill_value = Σ(usage × outcome_delta_vs_baseline).
+ *
+ * Each usage event is weighted by the outcome delta it produced vs the
+ * baseline skill. Events outside the 7-day window are excluded.
+ *
+ * @param skillId                 - The skill being measured.
+ * @param usageEvents             - All usage events for this skill.
+ * @param outcomeDeltaCalculator  - Consumer-provided function: event → delta.
+ * @param nowDate                 - Optional override for "now" (deterministic tests).
+ */
+export declare function computeSkillValue(skillId: string, usageEvents: UsageEvent[], outcomeDeltaCalculator: (event: UsageEvent) => number, nowDate?: Date): SkillValueResult;
+/**
+ * Compute skill_value for multiple skills and rank them descending.
+ */
+export declare function rankSkillsByValue(skills: Array<{
+    skillId: string;
+    usageEvents: UsageEvent[];
+    outcomeDeltaCalculator: (event: UsageEvent) => number;
+}>, nowDate?: Date): SkillValueResult[];
+//# sourceMappingURL=value-metric.d.ts.map

package/dist/skill-loop/value-metric.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-metric.d.ts","sourceRoot":"","sources":["../../src/skill-loop/value-metric.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,MAAM,WAAW,UAAU;IACzB,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;CACnB;AAYD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,UAAU,EAAE,EACzB,sBAAsB,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,MAAM,EACrD,OAAO,CAAC,EAAE,IAAI,GACb,gBAAgB,CA8BlB;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,KAAK,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,sBAAsB,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,MAAM,CAAC;CACvD,CAAC,EACF,OAAO,CAAC,EAAE,IAAI,GACb,gBAAgB,EAAE,CAMpB"}

package/dist/skill-loop/value-metric.js

@@ -0,0 +1,69 @@
+/**
+ * src/skill-loop/value-metric.ts
+ *
+ * skill_value formula: cumulative weekly metric.
+ *
+ *   skill_value = Σ(usage_count × outcome_delta_vs_baseline)
+ *
+ * Consumer provides an outcomeDeltaCalculator function that returns the
+ * outcome delta for a given usage event. The metric is cumulative over a
+ * sliding 7-day window.
+ *
+ * @module skill-loop/value-metric
+ */
+// ---------------------------------------------------------------------------
+// 7-day sliding window constant
+// ---------------------------------------------------------------------------
+const WEEK_MS = 7 * 24 * 60 * 60 * 1_000;
+// ---------------------------------------------------------------------------
+// computeSkillValue
+// ---------------------------------------------------------------------------
+/**
+ * Compute skill_value = Σ(usage × outcome_delta_vs_baseline).
+ *
+ * Each usage event is weighted by the outcome delta it produced vs the
+ * baseline skill. Events outside the 7-day window are excluded.
+ *
+ * @param skillId                 - The skill being measured.
+ * @param usageEvents             - All usage events for this skill.
+ * @param outcomeDeltaCalculator  - Consumer-provided function: event → delta.
+ * @param nowDate                 - Optional override for "now" (deterministic tests).
+ */
+export function computeSkillValue(skillId, usageEvents, outcomeDeltaCalculator, nowDate) {
+    const now = nowDate ?? new Date();
+    const windowEnd = now.toISOString();
+    const windowStart = new Date(now.getTime() - WEEK_MS).toISOString();
+    // Filter to events within the 7-day window
+    const windowEvents = usageEvents.filter((e) => {
+        const ts = e.timestamp;
+        return ts >= windowStart && ts <= windowEnd;
+    });
+    // skill_value = Σ(usage × outcome_delta)
+    // Each event counts as 1 usage unit.
+    let skillValue = 0;
+    let totalOutcomeDelta = 0;
+    for (const event of windowEvents) {
+        const delta = outcomeDeltaCalculator(event);
+        skillValue += 1 * delta; // usage_count per event = 1
+        totalOutcomeDelta += delta;
+    }
+    return {
+        skillId,
+        skillValue,
+        usageCount: windowEvents.length,
+        totalOutcomeDelta,
+        windowStart,
+        windowEnd,
+    };
+}
+// ---------------------------------------------------------------------------
+// computeAggregateSkillValue (multi-skill comparison helper)
+// ---------------------------------------------------------------------------
+/**
+ * Compute skill_value for multiple skills and rank them descending.
+ */
+export function rankSkillsByValue(skills, nowDate) {
+    const results = skills.map(({ skillId, usageEvents, outcomeDeltaCalculator }) => computeSkillValue(skillId, usageEvents, outcomeDeltaCalculator, nowDate));
+    return results.sort((a, b) => b.skillValue - a.skillValue);
+}
+//# sourceMappingURL=value-metric.js.map

package/dist/skill-loop/value-metric.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-metric.js","sourceRoot":"","sources":["../../src/skill-loop/value-metric.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA6BH,8EAA8E;AAC9E,gCAAgC;AAChC,8EAA8E;AAE9E,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC;AAEzC,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAe,EACf,WAAyB,EACzB,sBAAqD,EACrD,OAAc;IAEd,MAAM,GAAG,GAAG,OAAO,IAAI,IAAI,IAAI,EAAE,CAAC;IAClC,MAAM,SAAS,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IACpC,MAAM,WAAW,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;IAEpE,2CAA2C;IAC3C,MAAM,YAAY,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QAC5C,MAAM,EAAE,GAAG,CAAC,CAAC,SAAS,CAAC;QACvB,OAAO,EAAE,IAAI,WAAW,IAAI,EAAE,IAAI,SAAS,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEH,yCAAyC;IACzC,qCAAqC;IACrC,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,iBAAiB,GAAG,CAAC,CAAC;IAE1B,KAAK,MAAM,KAAK,IAAI,YAAY,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC;QAC5C,UAAU,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,4BAA4B;QACrD,iBAAiB,IAAI,KAAK,CAAC;IAC7B,CAAC;IAED,OAAO;QACL,OAAO;QACP,UAAU;QACV,UAAU,EAAE,YAAY,CAAC,MAAM;QAC/B,iBAAiB;QACjB,WAAW;QACX,SAAS;KACV,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,6DAA6D;AAC7D,8EAA8E;AAE9E;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAIE,EACF,OAAc;IAEd,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CACxB,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,EAAE,EAAE,CACnD,iBAAiB,CAAC,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,OAAO,CAAC,CAC3E,CAAC;IACF,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;AAC7D,CAAC"}

package/dist/skill-loop/versioning.d.ts

@@ -0,0 +1,36 @@
+/**
+ * src/skill-loop/versioning.ts
+ *
+ * Skill version management — semver bumping and version record type.
+ *
+ * Bump rules:
+ *   - reflexion / ab_winner  → minor bump (1.0.0 → 1.1.0)
+ *   - manual                 → major bump (1.0.0 → 2.0.0)
+ *   - initial                → no-op (returns "1.0.0" baseline)
+ *
+ * @module skill-loop/versioning
+ */
+export interface SkillVersion {
+    skillId: string;
+    /** Semver string: "1.0.0", "1.1.0", etc. */
+    version: string;
+    parentSkillId: string | null;
+    mutationType: "initial" | "reflexion" | "ab_winner" | "manual";
+    /** SHA-256 of the source cycle trace. */
+    replayRoot: string;
+    createdAt: Date;
+}
+/**
+ * Bump a semver string according to mutation type.
+ *
+ * - initial    → returns "1.0.0" (baseline, not a bump)
+ * - reflexion  → minor bump
+ * - ab_winner  → minor bump
+ * - manual     → major bump
+ *
+ * @param current      - Current semver string e.g. "1.2.3".
+ * @param mutationType - The kind of mutation that produced the new version.
+ * @returns New semver string.
+ */
+export declare function bumpVersion(current: string, mutationType: SkillVersion["mutationType"]): string;
+//# sourceMappingURL=versioning.d.ts.map

package/dist/skill-loop/versioning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioning.d.ts","sourceRoot":"","sources":["../../src/skill-loop/versioning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,YAAY,EAAE,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC/D,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,IAAI,CAAC;CACjB;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,YAAY,CAAC,cAAc,CAAC,GACzC,MAAM,CA2BR"}

package/dist/skill-loop/versioning.js

@@ -0,0 +1,47 @@
+/**
+ * src/skill-loop/versioning.ts
+ *
+ * Skill version management — semver bumping and version record type.
+ *
+ * Bump rules:
+ *   - reflexion / ab_winner  → minor bump (1.0.0 → 1.1.0)
+ *   - manual                 → major bump (1.0.0 → 2.0.0)
+ *   - initial                → no-op (returns "1.0.0" baseline)
+ *
+ * @module skill-loop/versioning
+ */
+// ---------------------------------------------------------------------------
+// Version bumping
+// ---------------------------------------------------------------------------
+/**
+ * Bump a semver string according to mutation type.
+ *
+ * - initial    → returns "1.0.0" (baseline, not a bump)
+ * - reflexion  → minor bump
+ * - ab_winner  → minor bump
+ * - manual     → major bump
+ *
+ * @param current      - Current semver string e.g. "1.2.3".
+ * @param mutationType - The kind of mutation that produced the new version.
+ * @returns New semver string.
+ */
+export function bumpVersion(current, mutationType) {
+    if (mutationType === "initial") {
+        return "1.0.0";
+    }
+    const parts = current.split(".");
+    if (parts.length !== 3) {
+        throw new Error(`bumpVersion: invalid semver "${current}" — expected "MAJOR.MINOR.PATCH"`);
+    }
+    const major = parseInt(parts[0], 10);
+    const minor = parseInt(parts[1], 10);
+    if (isNaN(major) || isNaN(minor)) {
+        throw new Error(`bumpVersion: non-numeric semver components in "${current}"`);
+    }
+    if (mutationType === "manual") {
+        return `${major + 1}.0.0`;
+    }
+    // reflexion | ab_winner → minor bump
+    return `${major}.${minor + 1}.0`;
+}
+//# sourceMappingURL=versioning.js.map

package/dist/skill-loop/versioning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioning.js","sourceRoot":"","sources":["../../src/skill-loop/versioning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAiBH,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CACzB,OAAe,EACf,YAA0C;IAE1C,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,gCAAgC,OAAO,kCAAkC,CAC1E,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACrC,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAErC,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,kDAAkD,OAAO,GAAG,CAC7D,CAAC;IACJ,CAAC;IAED,IAAI,YAAY,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,GAAG,KAAK,GAAG,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED,qCAAqC;IACrC,OAAO,GAAG,KAAK,IAAI,KAAK,GAAG,CAAC,IAAI,CAAC;AACnC,CAAC"}