usertrust 0.1.0

package/dist/policy/pii.js

@@ -0,0 +1,124 @@
+/**
+ * PII Detector
+ *
+ * Pattern-based PII detection for event payloads.
+ * Recursively scans strings in objects/arrays and returns
+ * which PII types were found and at which paths.
+ *
+ * Pure module — no side effects, no network calls.
+ *
+ * Detects: email, phone, SSN, credit card (Luhn-validated), IPv4.
+ *
+ * Adapted from Field Project fermion/src/higgs/pii-detector.ts.
+ */
+/** RFC 5322 simplified — local@domain.tld */
+function isEmail(value) {
+    return /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/.test(value);
+}
+/** US/international phone: +1-234-567-8901, (234) 567-8901, 234.567.8901, etc. */
+function isPhoneNumber(value) {
+    const stripped = value.replace(/\s+/g, "");
+    return /(?:\+?\d{1,3}[-.\s()]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}/.test(stripped);
+}
+/** US SSN: XXX-XX-XXXX (with dashes required to avoid false positives) */
+function isSSN(value) {
+    return /\b\d{3}-\d{2}-\d{4}\b/.test(value);
+}
+/** IPv4 address: 0-255.0-255.0-255.0-255 */
+function isIPv4(value) {
+    const match = value.match(/\b(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})\b/);
+    if (!match)
+        return false;
+    return [match[1], match[2], match[3], match[4]].every((octet) => {
+        const n = Number(octet);
+        return n >= 0 && n <= 255;
+    });
+}
+/**
+ * Credit card number detection.
+ * Finds 13-19 digit sequences (with optional dashes/spaces) and
+ * validates them using the Luhn algorithm.
+ */
+function isCreditCard(value) {
+    const candidates = value.match(/\b[\d][\d\s-]{11,22}[\d]\b/g);
+    if (!candidates)
+        return false;
+    return candidates.some((candidate) => {
+        const digits = candidate.replace(/[\s-]/g, "");
+        if (digits.length < 13 || digits.length > 19)
+            return false;
+        if (!/^\d+$/.test(digits))
+            return false;
+        return luhnCheck(digits);
+    });
+}
+/** Luhn algorithm for credit card validation. */
+function luhnCheck(digits) {
+    let sum = 0;
+    let alternate = false;
+    for (let i = digits.length - 1; i >= 0; i--) {
+        let n = Number(digits[i]);
+        if (alternate) {
+            n *= 2;
+            if (n > 9)
+                n -= 9;
+        }
+        sum += n;
+        alternate = !alternate;
+    }
+    return sum % 10 === 0;
+}
+const PII_PATTERNS = [
+    { type: "email", test: isEmail },
+    { type: "phone", test: isPhoneNumber },
+    { type: "ssn", test: isSSN },
+    { type: "credit_card", test: isCreditCard },
+    { type: "ipv4", test: isIPv4 },
+];
+// ---------------------------------------------------------------------------
+// Recursive scanner
+// ---------------------------------------------------------------------------
+/**
+ * Detect PII in any value by recursively scanning strings in objects/arrays.
+ *
+ * Returns which PII types were found and at which dot-paths.
+ */
+export function detectPII(data) {
+    const types = new Set();
+    const paths = [];
+    scanValue(data, "", types, paths);
+    return {
+        found: types.size > 0,
+        types: [...types],
+        paths,
+    };
+}
+function scanValue(value, currentPath, types, paths) {
+    if (typeof value === "string") {
+        scanString(value, currentPath, types, paths);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            const itemPath = currentPath ? `${currentPath}[${i}]` : `[${i}]`;
+            scanValue(value[i], itemPath, types, paths);
+        }
+        return;
+    }
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        for (const key of Object.keys(record)) {
+            const fieldPath = currentPath ? `${currentPath}.${key}` : key;
+            scanValue(record[key], fieldPath, types, paths);
+        }
+    }
+}
+function scanString(value, currentPath, types, paths) {
+    for (const pattern of PII_PATTERNS) {
+        if (pattern.test(value)) {
+            types.add(pattern.type);
+            paths.push(currentPath ? `${currentPath}(${pattern.type})` : `(${pattern.type})`);
+        }
+    }
+}
+//# sourceMappingURL=pii.js.map

package/dist/policy/pii.js.map

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

package/dist/proxy.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Proxy Mode — Remote Governance Connection
+ *
+ * When `opts.proxy` is set, governance flows through the remote proxy
+ * instead of a local TigerBeetle instance. This is a stub for v1 —
+ * the real implementation will HTTP POST to proxy.usertools.ai.
+ */
+export interface ProxySpendParams {
+    model: string;
+    estimatedCost: number;
+    actor: string;
+}
+export interface ProxySpendResult {
+    transferId: string;
+    estimatedCost: number;
+}
+export interface ProxyConnection {
+    spend(params: ProxySpendParams): Promise<ProxySpendResult>;
+    settle(transferId: string, actualCost: number): Promise<void>;
+    void(transferId: string): Promise<void>;
+    destroy(): void;
+    readonly url: string;
+    readonly key: string | undefined;
+}
+/**
+ * Connect to a remote governance proxy.
+ *
+ * Stub implementation for v1 — all operations succeed immediately
+ * with synthetic data. Real implementation will HTTP POST to the
+ * proxy URL with the provided API key.
+ */
+export declare function connectProxy(url: string, key?: string): ProxyConnection;
+//# sourceMappingURL=proxy.d.ts.map

package/dist/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC/B,KAAK,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC3D,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,OAAO,IAAI,IAAI,CAAC;IAChB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,eAAe,CAoBvE"}

package/dist/proxy.js

@@ -0,0 +1,36 @@
+/**
+ * Proxy Mode — Remote Governance Connection
+ *
+ * When `opts.proxy` is set, governance flows through the remote proxy
+ * instead of a local TigerBeetle instance. This is a stub for v1 —
+ * the real implementation will HTTP POST to proxy.usertools.ai.
+ */
+/**
+ * Connect to a remote governance proxy.
+ *
+ * Stub implementation for v1 — all operations succeed immediately
+ * with synthetic data. Real implementation will HTTP POST to the
+ * proxy URL with the provided API key.
+ */
+export function connectProxy(url, key) {
+    return {
+        url,
+        key,
+        async spend(params) {
+            return {
+                transferId: `proxy_${Date.now().toString(36)}`,
+                estimatedCost: params.estimatedCost,
+            };
+        },
+        async settle(_transferId, _actualCost) {
+            // Stub: no-op — real implementation will POST settlement
+        },
+        async void(_transferId) {
+            // Stub: no-op — real implementation will POST void
+        },
+        destroy() {
+            // Stub: no-op — real implementation will close HTTP connection pool
+        },
+    };
+}
+//# sourceMappingURL=proxy.js.map

package/dist/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAsBH;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW,EAAE,GAAY;IACrD,OAAO;QACN,GAAG;QACH,GAAG;QACH,KAAK,CAAC,KAAK,CAAC,MAAwB;YACnC,OAAO;gBACN,UAAU,EAAE,SAAS,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE;gBAC9C,aAAa,EAAE,MAAM,CAAC,aAAa;aACnC,CAAC;QACH,CAAC;QACD,KAAK,CAAC,MAAM,CAAC,WAAmB,EAAE,WAAmB;YACpD,yDAAyD;QAC1D,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,WAAmB;YAC7B,mDAAmD;QACpD,CAAC;QACD,OAAO;YACN,oEAAoE;QACrE,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/resilience/circuit.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Circuit Breaker — per-provider failure isolation
+ *
+ * Prevents cascading failures by tracking consecutive errors per key
+ * and short-circuiting execution when a failure threshold is exceeded.
+ *
+ * State machine: closed → open → half-open → closed
+ *   - closed:    all requests pass through normally
+ *   - open:      requests are rejected immediately (fail-fast)
+ *   - half-open: a limited number of requests test recovery
+ */
+/** Circuit breaker state. */
+export type CircuitState = "closed" | "open" | "half-open";
+/** Configuration for a circuit breaker. */
+export interface CircuitBreakerConfig {
+    /** Number of consecutive failures before opening the circuit (default: 5). */
+    failureThreshold: number;
+    /** Milliseconds to wait before transitioning from open to half-open (default: 60 000). */
+    resetTimeoutMs: number;
+    /** Number of successful requests in half-open to close the circuit (default: 2). */
+    halfOpenSuccessThreshold: number;
+}
+/** Snapshot of breaker state for observability. */
+export interface CircuitBreakerSnapshot {
+    readonly state: CircuitState;
+    readonly consecutiveFailures: number;
+    readonly halfOpenSuccesses: number;
+    readonly lastFailureTime: number | null;
+    readonly lastStateChange: number;
+}
+/** Error thrown when the circuit is open. */
+export declare class CircuitOpenError extends Error {
+    readonly breakerKey: string;
+    constructor(key: string);
+}
+/**
+ * A single circuit breaker instance tracking failure state for one key.
+ */
+export declare class CircuitBreaker {
+    readonly key: string;
+    private readonly config;
+    private state;
+    private consecutiveFailures;
+    private halfOpenSuccesses;
+    private lastFailureTime;
+    private lastStateChange;
+    private readonly now;
+    constructor(key: string, config?: Partial<CircuitBreakerConfig>, clock?: () => number);
+    /** Get a read-only snapshot of the breaker state. */
+    snapshot(): CircuitBreakerSnapshot;
+    /**
+     * Get the current state, applying automatic open → half-open transition
+     * when the reset timeout has elapsed.
+     */
+    getState(): CircuitState;
+    /**
+     * Check whether a request should be allowed through.
+     * Throws CircuitOpenError if the circuit is open.
+     */
+    allowRequest(): void;
+    /** Record a successful request. */
+    recordSuccess(): void;
+    /** Record a failed request. */
+    recordFailure(): void;
+    /** Force-reset the breaker to closed state (for admin/testing). */
+    reset(): void;
+    private transitionTo;
+}
+/**
+ * Registry of circuit breakers keyed by string (e.g. provider, action).
+ * Lazily creates breakers on first access.
+ */
+export declare class CircuitBreakerRegistry {
+    private readonly breakers;
+    private readonly config;
+    private readonly clock;
+    constructor(config?: Partial<CircuitBreakerConfig>, clock?: () => number);
+    /** Get or create a breaker for the given key. */
+    get(key: string): CircuitBreaker;
+    /** Get a snapshot of all breakers. */
+    allSnapshots(): Record<string, CircuitBreakerSnapshot>;
+    /** Reset all breakers to closed state. */
+    resetAll(): void;
+    /** Get the number of tracked breakers. */
+    get size(): number;
+}
+//# sourceMappingURL=circuit.d.ts.map

package/dist/resilience/circuit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit.d.ts","sourceRoot":"","sources":["../../src/resilience/circuit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,6BAA6B;AAC7B,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACpC,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,CAAC;IACzB,0FAA0F;IAC1F,cAAc,EAAE,MAAM,CAAC;IACvB,oFAAoF;IACpF,wBAAwB,EAAE,MAAM,CAAC;CACjC;AAED,mDAAmD;AACnD,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CACjC;AAED,6CAA6C;AAC7C,qBAAa,gBAAiB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,GAAG,EAAE,MAAM;CAKvB;AAgBD;;GAEG;AACH,qBAAa,cAAc;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEvB,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,MAAM;IAOrF,qDAAqD;IACrD,QAAQ,IAAI,sBAAsB;IAUlC;;;OAGG;IACH,QAAQ,IAAI,YAAY;IAWxB;;;OAGG;IACH,YAAY,IAAI,IAAI;IAQpB,mCAAmC;IACnC,aAAa,IAAI,IAAI;IAYrB,+BAA+B;IAC/B,aAAa,IAAI,IAAI;IAYrB,mEAAmE;IACnE,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,YAAY;CAUpB;AAMD;;;GAGG;AACH,qBAAa,sBAAsB;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;IAC9D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;gBAEvC,MAAM,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,MAAM;IAKxE,iDAAiD;IACjD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc;IAShC,sCAAsC;IACtC,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC;IAQtD,0CAA0C;IAC1C,QAAQ,IAAI,IAAI;IAMhB,0CAA0C;IAC1C,IAAI,IAAI,IAAI,MAAM,CAEjB;CACD"}

package/dist/resilience/circuit.js

@@ -0,0 +1,167 @@
+/**
+ * Circuit Breaker — per-provider failure isolation
+ *
+ * Prevents cascading failures by tracking consecutive errors per key
+ * and short-circuiting execution when a failure threshold is exceeded.
+ *
+ * State machine: closed → open → half-open → closed
+ *   - closed:    all requests pass through normally
+ *   - open:      requests are rejected immediately (fail-fast)
+ *   - half-open: a limited number of requests test recovery
+ */
+/** Error thrown when the circuit is open. */
+export class CircuitOpenError extends Error {
+    breakerKey;
+    constructor(key) {
+        super(`Circuit breaker "${key}" is open — request rejected`);
+        this.name = "CircuitOpenError";
+        this.breakerKey = key;
+    }
+}
+// ---------------------------------------------------------------------------
+// Default config
+// ---------------------------------------------------------------------------
+const DEFAULT_CONFIG = {
+    failureThreshold: 5,
+    resetTimeoutMs: 60_000,
+    halfOpenSuccessThreshold: 2,
+};
+// ---------------------------------------------------------------------------
+// CircuitBreaker
+// ---------------------------------------------------------------------------
+/**
+ * A single circuit breaker instance tracking failure state for one key.
+ */
+export class CircuitBreaker {
+    key;
+    config;
+    state = "closed";
+    consecutiveFailures = 0;
+    halfOpenSuccesses = 0;
+    lastFailureTime = null;
+    lastStateChange;
+    now;
+    constructor(key, config, clock) {
+        this.key = key;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.now = clock ?? Date.now;
+        this.lastStateChange = this.now();
+    }
+    /** Get a read-only snapshot of the breaker state. */
+    snapshot() {
+        return {
+            state: this.getState(),
+            consecutiveFailures: this.consecutiveFailures,
+            halfOpenSuccesses: this.halfOpenSuccesses,
+            lastFailureTime: this.lastFailureTime,
+            lastStateChange: this.lastStateChange,
+        };
+    }
+    /**
+     * Get the current state, applying automatic open → half-open transition
+     * when the reset timeout has elapsed.
+     */
+    getState() {
+        if (this.state === "open" &&
+            this.lastFailureTime !== null &&
+            this.now() - this.lastFailureTime >= this.config.resetTimeoutMs) {
+            this.transitionTo("half-open");
+        }
+        return this.state;
+    }
+    /**
+     * Check whether a request should be allowed through.
+     * Throws CircuitOpenError if the circuit is open.
+     */
+    allowRequest() {
+        const current = this.getState();
+        if (current === "open") {
+            throw new CircuitOpenError(this.key);
+        }
+        // closed and half-open both allow requests
+    }
+    /** Record a successful request. */
+    recordSuccess() {
+        if (this.state === "half-open") {
+            this.halfOpenSuccesses++;
+            if (this.halfOpenSuccesses >= this.config.halfOpenSuccessThreshold) {
+                this.transitionTo("closed");
+            }
+        }
+        else {
+            // Reset failure count on success in closed state
+            this.consecutiveFailures = 0;
+        }
+    }
+    /** Record a failed request. */
+    recordFailure() {
+        this.consecutiveFailures++;
+        this.lastFailureTime = this.now();
+        if (this.state === "half-open") {
+            // Any failure in half-open reopens the circuit
+            this.transitionTo("open");
+        }
+        else if (this.consecutiveFailures >= this.config.failureThreshold) {
+            this.transitionTo("open");
+        }
+    }
+    /** Force-reset the breaker to closed state (for admin/testing). */
+    reset() {
+        this.transitionTo("closed");
+    }
+    transitionTo(newState) {
+        this.state = newState;
+        this.lastStateChange = this.now();
+        if (newState === "closed") {
+            this.consecutiveFailures = 0;
+            this.halfOpenSuccesses = 0;
+        }
+        else if (newState === "half-open") {
+            this.halfOpenSuccesses = 0;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+/**
+ * Registry of circuit breakers keyed by string (e.g. provider, action).
+ * Lazily creates breakers on first access.
+ */
+export class CircuitBreakerRegistry {
+    breakers = new Map();
+    config;
+    clock;
+    constructor(config, clock) {
+        this.config = config ?? {};
+        this.clock = clock;
+    }
+    /** Get or create a breaker for the given key. */
+    get(key) {
+        let breaker = this.breakers.get(key);
+        if (breaker === undefined) {
+            breaker = new CircuitBreaker(key, this.config, this.clock);
+            this.breakers.set(key, breaker);
+        }
+        return breaker;
+    }
+    /** Get a snapshot of all breakers. */
+    allSnapshots() {
+        const result = {};
+        for (const [key, breaker] of this.breakers) {
+            result[key] = breaker.snapshot();
+        }
+        return result;
+    }
+    /** Reset all breakers to closed state. */
+    resetAll() {
+        for (const breaker of this.breakers.values()) {
+            breaker.reset();
+        }
+    }
+    /** Get the number of tracked breakers. */
+    get size() {
+        return this.breakers.size;
+    }
+}
+//# sourceMappingURL=circuit.js.map

package/dist/resilience/circuit.js.map

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

package/dist/resilience/scope.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Scope Locking — minimatch-based overlap detection & lease management
+ *
+ * Prevents conflicts between parallel workers by tracking scope-based leases.
+ * Each lease locks a set of glob patterns; overlapping patterns from different
+ * actors are rejected.
+ *
+ * Store path: `.usertools/leases.json`
+ */
+export type LeaseStatus = "active" | "released" | "expired" | "revoked";
+export interface Lease {
+    lease_id: string;
+    actor: string;
+    scope: string[];
+    intent: string;
+    issued_at: string;
+    expires_at: string;
+    status: LeaseStatus;
+    last_renewed_at?: string;
+}
+export interface LeaseStore {
+    [lease_id: string]: Lease;
+}
+export interface AcquireLeaseOptions {
+    actor: string;
+    scope: string[];
+    intent: string;
+    /** Lease time-to-live in minutes (default: 60). */
+    ttlMin?: number;
+}
+export interface LeaseConflict {
+    lease: Lease;
+    overlappingPatterns: string[];
+}
+/**
+ * Set the store directory path (for testing).
+ */
+export declare function setStoreDir(dir: string): void;
+/**
+ * Get the current store directory.
+ */
+export declare function getStoreDir(): string;
+/**
+ * Check if two scope patterns overlap.
+ *
+ * Two patterns overlap when:
+ * 1. Either literally matches the other via minimatch, OR
+ * 2. They share a common base prefix (e.g. `src/**` and `src/foo/**`)
+ */
+export declare function scopesOverlap(scopeA: string[], scopeB: string[]): boolean;
+/**
+ * Check if a file matches any of the scope patterns.
+ */
+export declare function fileMatchesScope(file: string, scope: string[]): boolean;
+/**
+ * Scope-based lease manager.
+ *
+ * Provides `acquireLease`, `releaseLease`, `findConflicts`, and `expireStale`
+ * for coordinating parallel workers operating on overlapping file scopes.
+ */
+export declare class ScopeManager {
+    private readonly clock;
+    constructor(clock?: () => number);
+    /**
+     * Acquire a lease for the given scope.
+     * Throws if scope overlaps with another actor's active lease.
+     */
+    acquireLease(options: AcquireLeaseOptions): Lease;
+    /**
+     * Renew an existing lease, extending its TTL.
+     */
+    renewLease(leaseId: string, ttlMin?: number): Lease;
+    /**
+     * Release a lease, marking it as released.
+     */
+    releaseLease(leaseId: string): Lease;
+    /**
+     * Find conflicts for a proposed scope against active leases.
+     */
+    findConflicts(scope: string[], excludeActor?: string): LeaseConflict[];
+    /**
+     * Expire stale leases and persist the result.
+     * Returns the number of leases expired.
+     */
+    expireStale(): number;
+    /**
+     * Get all active leases.
+     */
+    getActiveLeases(): Lease[];
+    /**
+     * Get a lease by ID.
+     */
+    getLease(leaseId: string): Lease | undefined;
+    private findConflictsInStore;
+    private expireStaleInStore;
+}
+//# sourceMappingURL=scope.d.ts.map

package/dist/resilience/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../src/resilience/scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAWH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAExE,MAAM,WAAW,KAAK;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,WAAW,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IAC1B,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,KAAK,CAAC;IACb,mBAAmB,EAAE,MAAM,EAAE,CAAC;CAC9B;AAQD;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAgDD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAgBzE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAOvE;AAMD;;;;;GAKG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAEzB,KAAK,CAAC,EAAE,MAAM,MAAM;IAIhC;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,KAAK;IAsCjD;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAK,GAAG,KAAK;IAkB/C;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK;IAcpC;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE;IAMtE;;;OAGG;IACH,WAAW,IAAI,MAAM;IASrB;;OAEG;IACH,eAAe,IAAI,KAAK,EAAE;IAK1B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAO5C,OAAO,CAAC,oBAAoB;IAsB5B,OAAO,CAAC,kBAAkB;CAa1B"}