@vibesdotdev/storage 0.0.2 → 1.0.0-rc.4

package/dist/retention/storage.retention-sweep.impl.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Storage Retention Sweep Job Implementation
+ *
+ * Policy lives in `sweep.ts`. The job is available for explicit dispatch and
+ * its schedule is opt-in; host activation does not delete records.
+ */
+import type { JobDescriptor, JobImplementation, JobExecutionContext } from '@vibesdotdev/kernel/kinds';
+import { type VibesRuntime } from '@vibesdotdev/kernel';
+import type { RetentionSweepJobInput, RetentionSweepJobOutput } from './storage.retention-sweep.schema.ts';
+export declare class StorageRetentionSweepJob implements JobImplementation<RetentionSweepJobInput, RetentionSweepJobOutput> {
+    readonly id: string;
+    readonly descriptor: JobDescriptor;
+    readonly type: "progress";
+    readonly isolation: "inline";
+    private runtime;
+    constructor(descriptor: JobDescriptor, context: {
+        runtime: VibesRuntime;
+    });
+    handle(context: JobExecutionContext<RetentionSweepJobInput>): Promise<RetentionSweepJobOutput>;
+}
+export default StorageRetentionSweepJob;
+//# sourceMappingURL=storage.retention-sweep.impl.d.ts.map

package/dist/retention/storage.retention-sweep.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.retention-sweep.impl.d.ts","sourceRoot":"","sources":["../../src/retention/storage.retention-sweep.impl.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACvG,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEzE,OAAO,KAAK,EACX,sBAAsB,EACtB,uBAAuB,EACvB,MAAM,qCAAqC,CAAC;AAM7C,qBAAa,wBACZ,YAAW,iBAAiB,CAAC,sBAAsB,EAAE,uBAAuB,CAAC;IAE7E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAG,UAAU,CAAU;IACpC,QAAQ,CAAC,SAAS,EAAG,QAAQ,CAAU;IAEvC,OAAO,CAAC,OAAO,CAAe;gBAElB,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE;QAAE,OAAO,EAAE,YAAY,CAAA;KAAE;IAMnE,MAAM,CACX,OAAO,EAAE,mBAAmB,CAAC,sBAAsB,CAAC,GAClD,OAAO,CAAC,uBAAuB,CAAC;CAoDnC;AAED,eAAe,wBAAwB,CAAC"}

package/dist/retention/storage.retention-sweep.impl.js

@@ -0,0 +1,78 @@
+/**
+ * Storage Retention Sweep Job Implementation
+ *
+ * Policy lives in `sweep.ts`. The job is available for explicit dispatch and
+ * its schedule is opt-in; host activation does not delete records.
+ */
+import { CapabilityError } from '@vibesdotdev/kernel';
+import { sweepDeclaredRetention } from "./sweep.js";
+import { reclaimDatabases } from "./reclaim.js";
+import { sweepTmpScratch } from "./tmp-scratch.js";
+import { listRootDatabases, resolveVibesRoots } from "./roots.js";
+export class StorageRetentionSweepJob {
+    id;
+    descriptor;
+    type = 'progress';
+    isolation = 'inline';
+    runtime;
+    constructor(descriptor, context) {
+        this.id = descriptor.id;
+        this.descriptor = descriptor;
+        this.runtime = context.runtime;
+    }
+    async handle(context) {
+        if (context.signal?.aborted)
+            throw new CapabilityError('Retention sweep was cancelled.', 'CANCELLED', { reason: 'retention-sweep-cancelled' });
+        const { dryRun, recordId, now, reclaim } = context.data;
+        const sweepOptions = { runtime: this.runtime, dryRun };
+        if (recordId)
+            sweepOptions.recordId = recordId;
+        if (now)
+            sweepOptions.now = now;
+        const result = await sweepDeclaredRetention(sweepOptions);
+        await context.events?.progress(60);
+        // Deletes free SQLite pages onto a freelist; only a VACUUM returns them
+        // to the filesystem. Skipping this would ship the exact gap this job was
+        // written to close — a sweep that reports a million rows removed while
+        // the disk does not move. `reclaimDatabases` applies its own
+        // minimum-bytes threshold, so a quiet night is cheap.
+        let reclaimedBytes = 0;
+        const roots = await resolveVibesRoots(this.runtime);
+        const tmp = await sweepTmpScratch(this.runtime, roots, { now, deleteExpired: !dryRun });
+        let reclaimFailures = 0;
+        if (reclaim && !dryRun) {
+            for (const root of roots) {
+                const outcome = await reclaimDatabases(this.runtime, await listRootDatabases(this.runtime, root), { signal: context.signal });
+                reclaimedBytes += outcome.bytesReclaimed;
+                reclaimFailures += outcome.databases.filter((database) => database.failure).length;
+            }
+        }
+        // A per-record error does not fail the batch — one unresolvable record
+        // must not stop the other tables from being bounded — but it must be
+        // visible rather than absorbed into a green result.
+        const errors = result.records.filter((r) => r.error);
+        const tmpFailures = tmp.roots.filter((root) => root.failure);
+        if (context.signal?.aborted)
+            throw new CapabilityError('Retention sweep was cancelled.', 'CANCELLED', { reason: 'retention-sweep-cancelled' });
+        if (errors.length > 0 || tmpFailures.length > 0 || reclaimFailures > 0) {
+            throw new CapabilityError('Retention sweep could not inspect every source.', 'UNAVAILABLE', {
+                reason: 'retention-sweep-failed',
+                details: { recordFailures: errors.length, tmpFailures: tmpFailures.length, reclaimFailures }
+            });
+        }
+        await context.events?.progress(100);
+        const output = {
+            success: true,
+            dryRun: result.dryRun,
+            examined: result.examined,
+            undeclared: result.undeclared,
+            records: result.records,
+            totalDeleted: result.totalDeleted,
+            reclaimedBytes,
+            tmp
+        };
+        return output;
+    }
+}
+export default StorageRetentionSweepJob;
+//# sourceMappingURL=storage.retention-sweep.impl.js.map

package/dist/retention/storage.retention-sweep.impl.js.map

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

package/dist/retention/storage.retention-sweep.schema.d.ts

@@ -0,0 +1,3 @@
+/** Compatibility exports for retention job schemas. */
+export * from '../schemas/retention/jobs.ts';
+//# sourceMappingURL=storage.retention-sweep.schema.d.ts.map

package/dist/retention/storage.retention-sweep.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.retention-sweep.schema.d.ts","sourceRoot":"","sources":["../../src/retention/storage.retention-sweep.schema.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,cAAc,8BAA8B,CAAC"}

package/dist/retention/storage.retention-sweep.schema.js

@@ -0,0 +1,3 @@
+/** Compatibility exports for retention job schemas. */
+export * from "../schemas/retention/jobs.js";
+//# sourceMappingURL=storage.retention-sweep.schema.js.map

package/dist/retention/storage.retention-sweep.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.retention-sweep.schema.js","sourceRoot":"","sources":["../../src/retention/storage.retention-sweep.schema.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,cAAc,8BAA8B,CAAC"}

package/dist/retention/sweep.d.ts

@@ -0,0 +1,31 @@
+import type { RetentionSweepResult } from '../schemas/retention/results.ts';
+export type { RetentionSweepRecordResult, RetentionSweepResult } from '../schemas/retention/results.ts';
+import { type RuntimeRef } from '@vibesdotdev/kernel';
+/**
+ * The runtime a sweep runs on: the `RuntimeRef` plugin activation hands out,
+ * which a full `VibesRuntime` (a worker job's) also satisfies.
+ *
+ * Enumeration goes through `query(...).descriptors()`, not `assets(...)`:
+ * `assets` exists only on the full `VibesRuntime`. Using the plugin view is
+ * what lets the same sweep run from activation AND from a worker job. The
+ * sweep reports to this runtime's Logging, never an ambient default.
+ */
+export type RetentionRuntime = RuntimeRef;
+export interface RetentionSweepOptions {
+    runtime: RetentionRuntime;
+    /** Report what would be removed, removing nothing. */
+    dryRun?: boolean;
+    /** Restrict to one `storage/record` id. */
+    recordId?: string;
+    /** Epoch ms to age against. Defaults to now; present for tests. */
+    now?: number;
+}
+/**
+ * Apply every declared retention policy.
+ *
+ * Never throws. A sweep that cannot run must not take down the CLI invocation
+ * or worker that hosts it — but it must also not report success, so failures
+ * land in per-record `error` fields the caller can surface.
+ */
+export declare function sweepDeclaredRetention(options: RetentionSweepOptions): Promise<RetentionSweepResult>;
+//# sourceMappingURL=sweep.d.ts.map

package/dist/retention/sweep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sweep.d.ts","sourceRoot":"","sources":["../../src/retention/sweep.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA8B,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACxG,YAAY,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAmCxG,OAAO,EAAqF,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAMzI;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC;AAE1C,MAAM,WAAW,qBAAqB;IACrC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,sDAAsD;IACtD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAuID;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC3C,OAAO,EAAE,qBAAqB,GAC5B,OAAO,CAAC,oBAAoB,CAAC,CAoC/B"}

package/dist/retention/sweep.js

@@ -0,0 +1,190 @@
+/**
+ * Enforce every `retention:` policy a `storage/record` descriptor declares.
+ *
+ * WHY GENERIC, AND WHY THIS IS THE DEFAULT.
+ *
+ * `runtime/src/schemas/retention.ts` gave descriptors a place to declare how
+ * long their rows may live, and said plainly: DECLARING IS NOT ENFORCING. It was
+ * right. Months later four descriptors carried a policy and exactly one of them
+ * — `external.file_accesses` — had an enforcer, hand-written in its own plugin.
+ * The other three declared a window that nothing read. `awareness_event` reached
+ * 610k rows / 907MB and `awareness_staged_item` 720k rows / 274MB under a
+ * declared policy, on a machine whose `.vibes` had reached 11GB.
+ *
+ * A per-table enforcer is how that happens: writing one is real work, so the
+ * next author declares the policy, means to wire it, and doesn't. This sweep
+ * inverts that. Anything that declares a window is enforced by default, and the
+ * work of adding a table is zero. A table that needs bespoke logic must say so
+ * out loud via `retention.enforcedBy`, which is greppable — the opposite of a
+ * table quietly falling between two mechanisms.
+ *
+ * PHYSICAL, NOT SOFT. `deleteMany` on a `softDelete` descriptor stamps
+ * `deletedAt` and keeps the bytes; `list()` then hides those rows, so the table
+ * looks pruned while growing forever. `maxAgeDays` says "drop entries older than
+ * this", so the sweep passes `force: true` and the rows actually leave. A policy
+ * that wants a recoverable grace tier is expressing something `maxAgeDays`
+ * cannot, and belongs behind `enforcedBy` with a job that says so.
+ *
+ * DELETING IS NOT RECLAIMING. Every `.vibes` database was created with
+ * `auto_vacuum = 0`, so a successful delete returns no disk — measured: 16,816
+ * free pages sitting in `sessions.db` after earlier deletes. Freeing space is
+ * `reclaim.ts`'s job, run after this one.
+ */
+import * as z from 'zod/v4';
+import { CaughtFailureSchema, valueFreeFailure } from '@vibesdotdev/kernel';
+import { normalizeRetention, retentionAgeField, retentionCutoff, RetentionSchema } from '@vibesdotdev/kernel/schemas/retention';
+import { getLogger } from '@vibesdotdev/logging';
+/**
+ * The fields of a `storage/record` descriptor the sweep reads, each parsed on
+ * its own: the retention declaration is read per record (an unparseable one is
+ * that record's reported skip, never a dropped record or a failed sweep).
+ */
+const SweptDescriptorSchema = z.object({
+    id: z.string().min(1),
+    tableName: z.string().optional(),
+    enabled: z.boolean().optional(),
+    retention: z.unknown().optional()
+});
+/** The swept fields of every registered record descriptor (the kind is checked first). */
+function listRecordDescriptors(runtime) {
+    if (!runtime.hasKind('storage/record'))
+        return [];
+    return runtime
+        .query('storage/record')
+        .descriptors()
+        .map((descriptor) => SweptDescriptorSchema.safeParse(descriptor))
+        .filter((parsed) => parsed.success)
+        .map((parsed) => parsed.data);
+}
+/** A failure as the sweep reports it: its value-free facts on one line. */
+function failureText(prefix, failure) {
+    const facts = valueFreeFailure(failure);
+    return [prefix, facts.name, facts.code, facts.reason].filter((part) => part !== undefined).join(' ');
+}
+/**
+ * Rows past the `maxEntries` cap.
+ *
+ * Implemented as "find the age of the Nth-newest row, delete everything older"
+ * rather than "select ids to delete", because the id list for an overgrown
+ * table is exactly the thing that is too large to hold.
+ */
+async function deleteBeyondCount(record, ageField, maxEntries, dryRun) {
+    const total = await record.count();
+    if (total <= maxEntries)
+        return 0;
+    // `offset: maxEntries - 1` is the LAST ROW KEPT, not the first row dropped.
+    // Offsetting by `maxEntries` names the first row to remove, and `< that`
+    // then spares it — leaving `maxEntries + 1` rows and a cap that is always
+    // one short of doing its job.
+    const boundary = await record.list({
+        orderBy: { [ageField]: 'desc' },
+        limit: 1,
+        offset: maxEntries - 1,
+        select: [ageField],
+        includeDeleted: true
+    });
+    const cutoff = boundary.items[0]?.[ageField];
+    // No usable boundary value means the age column is absent or null on the
+    // rows that matter. Deleting on that basis would be deleting on a guess.
+    if (cutoff === undefined || cutoff === null)
+        return 0;
+    // Rows sharing the boundary's exact age survive, so a table can sit slightly
+    // above the cap. Deliberate: keeping a few extra rows is recoverable, and
+    // `<=` would delete an arbitrary subset of a tie.
+    if (dryRun)
+        return await record.count({ [ageField]: { lt: cutoff } });
+    const result = await record.deleteMany({ [ageField]: { lt: cutoff } }, { force: true });
+    return result.count;
+}
+async function sweepOne(runtime, descriptor, now, dryRun) {
+    const recordId = descriptor.id;
+    const base = { recordId, deletedByAge: 0, deletedByCount: 0 };
+    if (descriptor.tableName)
+        base.tableName = descriptor.tableName;
+    if (descriptor.retention === undefined)
+        return { ...base, skipped: 'no retention declared' };
+    const declared = RetentionSchema.safeParse(descriptor.retention);
+    if (!declared.success)
+        return { ...base, skipped: 'unparseable retention declaration' };
+    const declaration = declared.data;
+    // A named owner runs instead of the sweep. Reported, never silent.
+    const policyObject = RetentionSchema.options[1].safeParse(declaration);
+    if (policyObject.success && policyObject.data.enforcedBy) {
+        return { ...base, skipped: `enforced by ${policyObject.data.enforcedBy}` };
+    }
+    const policy = normalizeRetention(declaration);
+    if (!policy)
+        return { ...base, skipped: 'unparseable retention declaration' };
+    const ageField = retentionAgeField(policy);
+    const cutoff = retentionCutoff(policy, now);
+    if (!cutoff && policy.maxEntries === undefined) {
+        // A policy with a reason but no limit looks covered and enforces nothing.
+        return { ...base, skipped: 'policy sets no enforceable limit' };
+    }
+    let record;
+    try {
+        record = await runtime.query('storage/record').withId(recordId).resolve();
+    }
+    catch (error) {
+        const failure = CaughtFailureSchema.parse(error);
+        return { ...base, error: failureText('could not resolve record:', failure), failure: valueFreeFailure(failure) };
+    }
+    try {
+        let deletedByAge = 0;
+        if (cutoff) {
+            const where = { [ageField]: { lt: cutoff.toISOString() } };
+            deletedByAge = dryRun
+                ? await record.count(where)
+                : (await record.deleteMany(where, { force: true })).count;
+        }
+        const deletedByCount = policy.maxEntries === undefined
+            ? 0
+            : await deleteBeyondCount(record, ageField, policy.maxEntries, dryRun);
+        return { ...base, deletedByAge, deletedByCount };
+    }
+    catch (error) {
+        const failure = CaughtFailureSchema.parse(error);
+        return { ...base, error: failureText('sweep failed:', failure), failure: valueFreeFailure(failure) };
+    }
+}
+/**
+ * Apply every declared retention policy.
+ *
+ * Never throws. A sweep that cannot run must not take down the CLI invocation
+ * or worker that hosts it — but it must also not report success, so failures
+ * land in per-record `error` fields the caller can surface.
+ */
+export async function sweepDeclaredRetention(options) {
+    const now = options.now ?? Date.now();
+    const dryRun = options.dryRun ?? false;
+    const descriptors = listRecordDescriptors(options.runtime).filter((d) => d.enabled !== false);
+    const undeclared = descriptors
+        .filter((d) => d.retention === undefined)
+        .map((d) => d.id)
+        .sort();
+    const targets = descriptors.filter((d) => {
+        if (options.recordId)
+            return d.id === options.recordId;
+        return Boolean(d.retention);
+    });
+    const records = [];
+    for (const descriptor of targets) {
+        records.push(await sweepOne(options.runtime, descriptor, now, dryRun));
+    }
+    const totalDeleted = records.reduce((sum, r) => sum + r.deletedByAge + r.deletedByCount, 0);
+    if (totalDeleted > 0) {
+        getLogger('storage:retention', options.runtime).info('Retention sweep removed rows', {
+            dryRun,
+            totalDeleted,
+            records: records.filter((r) => r.deletedByAge + r.deletedByCount > 0)
+        });
+    }
+    return {
+        examined: targets.length,
+        undeclared,
+        records,
+        totalDeleted,
+        dryRun
+    };
+}
+//# sourceMappingURL=sweep.js.map

package/dist/retention/sweep.js.map

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

package/dist/retention/tmp-scratch.d.ts

@@ -0,0 +1,35 @@
+/** Reclaim expired scratch only under authoritative directory custody. */
+import { type RuntimeRef } from '@vibesdotdev/kernel';
+import { type TmpSweepOptions, type TmpSweepResult } from './storage.retention-sweep.schema.ts';
+export { DEFAULT_TMP_TTL_MS, TMP_KEEP_MARKER, TmpSweepOptionsSchema } from './storage.retention-sweep.schema.ts';
+export type { TmpSweepOptions, TmpSweepResult } from './storage.retention-sweep.schema.ts';
+export declare function sweepTmpScratchForRoot(runtime: RuntimeRef, root: string, input?: TmpSweepOptions): Promise<TmpSweepResult>;
+export declare function sweepTmpScratch(runtime: RuntimeRef, roots: readonly string[], options?: TmpSweepOptions): Promise<{
+    roots: {
+        root: string;
+        scanned: number;
+        deleted: number;
+        bytesReclaimed: number;
+        candidates: {
+            path: string;
+            bytes: number;
+            modifiedAt: number;
+        }[];
+        candidateBytes: number;
+        kept: {
+            path: string;
+            reason: string;
+        }[];
+        skipped?: string | undefined;
+        failure?: {
+            name: string;
+            code?: string | undefined;
+            reason?: string | undefined;
+        } | undefined;
+    }[];
+    deleted: number;
+    bytesReclaimed: number;
+    candidates: number;
+    candidateBytes: number;
+}>;
+//# sourceMappingURL=tmp-scratch.d.ts.map

package/dist/retention/tmp-scratch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tmp-scratch.d.ts","sourceRoot":"","sources":["../../src/retention/tmp-scratch.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,OAAO,EAAkF,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAKtI,OAAO,EAAyB,KAAK,eAAe,EAAE,KAAK,cAAc,EAAmB,MAAM,qCAAqC,CAAC;AACxI,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AACjH,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAqD3F,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CA2DhI;AAED,wBAAsB,eAAe,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;GAU7G"}

package/dist/retention/tmp-scratch.js

@@ -0,0 +1,149 @@
+/** Reclaim expired scratch only under authoritative directory custody. */
+import { CapabilityError, CaughtFailureSchema, valueFreeFailure } from '@vibesdotdev/kernel';
+import { getLogger } from '@vibesdotdev/logging';
+import { hostStat, hostFileSystemOf } from "../host-files.js";
+import { ScratchCustodyReceiptSchema } from "./scratch-custody.js";
+import { TmpSweepOptionsSchema, TMP_KEEP_MARKER } from "./storage.retention-sweep.schema.js";
+export { DEFAULT_TMP_TTL_MS, TMP_KEEP_MARKER, TmpSweepOptionsSchema } from "./storage.retention-sweep.schema.js";
+/** No-follow, bounded metadata inspection. Unknown age and links preserve work. */
+async function inspectEntry(fs, path, budget) {
+    const pending = [path];
+    let modifiedAt = 0;
+    let bytes = 0;
+    while (pending.length > 0) {
+        if (budget.remaining-- <= 0)
+            return { reason: 'walk budget exhausted' };
+        const next = pending.pop();
+        if (!next)
+            break;
+        const stat = await fs.stat(next);
+        if (stat.kind !== 'file' && stat.kind !== 'directory')
+            return { reason: 'link or special entry' };
+        const mtime = stat.mtime ? Date.parse(stat.mtime) : Number.NaN;
+        if (!Number.isFinite(mtime))
+            return { reason: 'modification time unavailable' };
+        modifiedAt = Math.max(modifiedAt, mtime);
+        if (stat.kind === 'file') {
+            bytes += stat.size;
+            continue;
+        }
+        const children = await fs.list(next);
+        if (children.some((child) => child.name === TMP_KEEP_MARKER))
+            return { reason: 'keep marker' };
+        if (children.length + pending.length > budget.remaining)
+            return { reason: 'walk budget exhausted' };
+        for (const child of children)
+            pending.push(fs.join(next, child.name));
+    }
+    return { modifiedAt, bytes };
+}
+async function removeWithCustody(runtime, fs, result, path, cutoff, budget) {
+    const custody = await runtime.query('storage/scratch-custody').enabled().resolve();
+    const receipt = ScratchCustodyReceiptSchema.parse(await custody.acquire({ root: result.root, path }));
+    if (receipt.status === 'held') {
+        result.kept.push({ path, reason: 'active custody lease' });
+        return;
+    }
+    try {
+        // Recheck age and evidence inside the committed directory lease.
+        const inspected = await inspectEntry(fs, path, budget);
+        if (inspected.reason)
+            result.kept.push({ path, reason: inspected.reason });
+        else if (inspected.modifiedAt === undefined || inspected.bytes === undefined || inspected.modifiedAt >= cutoff) {
+            result.kept.push({ path, reason: 'touched within the TTL' });
+        }
+        else if (receipt.expiresAt <= Date.now()) {
+            result.kept.push({ path, reason: 'custody lease expired' });
+        }
+        else {
+            await fs.remove(path, { recursive: true });
+            result.deleted += 1;
+            result.bytesReclaimed += inspected.bytes;
+        }
+    }
+    finally {
+        await custody.release(receipt.token);
+    }
+}
+export async function sweepTmpScratchForRoot(runtime, root, input) {
+    const options = TmpSweepOptionsSchema.parse(input ?? {});
+    const logger = getLogger('storage:retention', runtime);
+    const result = { root, scanned: 0, deleted: 0, bytesReclaimed: 0, candidates: [], candidateBytes: 0, kept: [] };
+    const tmpRoot = `${root.replace(/\/+$/, '')}/tmp`;
+    try {
+        const fs = await hostFileSystemOf(runtime, 'retention-filesystem-unavailable');
+        const rootStat = await hostStat(fs, tmpRoot);
+        if (!rootStat)
+            return { ...result, skipped: 'no tmp directory' };
+        if (rootStat.kind !== 'directory')
+            return { ...result, skipped: 'tmp root is not a directory' };
+        const entries = await fs.list(tmpRoot);
+        if (entries.length > options.maxEntries)
+            return { ...result, skipped: 'root listing exceeds walk budget' };
+        const budget = { remaining: options.maxEntries };
+        const cutoff = (options.now ?? Date.now()) - options.ttlMs;
+        const protect = new Set(['p6-ripple', ...options.protect]);
+        for (const entry of entries) {
+            const path = fs.join(tmpRoot, entry.name);
+            result.scanned += 1;
+            if (protect.has(entry.name) || protect.has(path) || entry.name === TMP_KEEP_MARKER) {
+                result.kept.push({ path, reason: 'protected by name' });
+                continue;
+            }
+            try {
+                const inspected = await inspectEntry(fs, path, budget);
+                if (inspected.reason) {
+                    result.kept.push({ path, reason: inspected.reason });
+                }
+                else if (inspected.modifiedAt !== undefined && inspected.bytes !== undefined) {
+                    if (inspected.modifiedAt >= cutoff)
+                        result.kept.push({ path, reason: 'touched within the TTL' });
+                    else {
+                        result.candidates.push({ path, bytes: inspected.bytes, modifiedAt: inspected.modifiedAt });
+                        result.candidateBytes += inspected.bytes;
+                        if (options.deleteExpired) {
+                            const deletedBefore = result.deleted;
+                            try {
+                                await removeWithCustody(runtime, fs, result, path, cutoff, budget);
+                            }
+                            catch (cause) {
+                                const error = new CapabilityError('Scratch reclamation could not be certified.', 'UNAVAILABLE', { reason: 'scratch-reclamation-unavailable', cause });
+                                if (result.deleted === deletedBefore)
+                                    result.kept.push({ path, reason: 'custody or removal unavailable' });
+                                return { ...result, failure: valueFreeFailure(error), skipped: 'scratch reclamation unavailable' };
+                            }
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                const failure = CaughtFailureSchema.parse(error);
+                logger.warn('Tmp entry inspection failed; preserving entry', { path, error: valueFreeFailure(failure) });
+                return { ...result, failure: valueFreeFailure(failure), skipped: 'tmp entry inspection failed', kept: [...result.kept, { path, reason: 'inspection failed' }] };
+            }
+        }
+    }
+    catch (error) {
+        const failure = CaughtFailureSchema.parse(error);
+        logger.warn('Tmp inspection unavailable; preserving scratch', { root: tmpRoot, error: valueFreeFailure(failure) });
+        return { ...result, failure: valueFreeFailure(failure), skipped: 'tmp inspection unavailable' };
+    }
+    logger.info('Swept workspace tmp scratch', {
+        root: tmpRoot, scanned: result.scanned, candidates: result.candidates.length, candidateBytes: result.candidateBytes, kept: result.kept.length,
+        deleted: result.deleted, bytesReclaimed: result.bytesReclaimed
+    });
+    return result;
+}
+export async function sweepTmpScratch(runtime, roots, options) {
+    const results = [];
+    for (const root of roots)
+        results.push(await sweepTmpScratchForRoot(runtime, root, options));
+    return {
+        roots: results,
+        deleted: results.reduce((sum, result) => sum + result.deleted, 0),
+        bytesReclaimed: results.reduce((sum, result) => sum + result.bytesReclaimed, 0),
+        candidates: results.reduce((sum, result) => sum + result.candidates.length, 0),
+        candidateBytes: results.reduce((sum, result) => sum + result.candidateBytes, 0)
+    };
+}
+//# sourceMappingURL=tmp-scratch.js.map

package/dist/retention/tmp-scratch.js.map

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

package/dist/schemas/adapter-config.d.ts

@@ -0,0 +1,42 @@
+import * as z from 'zod/v4';
+/**
+ * An adapter's configuration as storage core hands it over: the runtime and
+ * path facts the manifest or record supplies, plus the descriptor's
+ * adapter-specific options. Each adapter parses the fields it owns.
+ */
+export declare const StorageAdapterConfigSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export type StorageAdapterConfig = z.infer<typeof StorageAdapterConfigSchema>;
+/** Adapter-specific health facts reported beside `healthy`. */
+export declare const StorageHealthDetailsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export type StorageHealthDetails = z.infer<typeof StorageHealthDetailsSchema>;
+/** An adapter's raw database connection (e.g. a bun:sqlite Database); the adapter's own callers know its type. */
+export declare const StorageDatabaseConnectionSchema: z.ZodUnknown;
+export type StorageDatabaseConnection = z.infer<typeof StorageDatabaseConnectionSchema>;
+/** A records collection keyed by record id, as the cloud settings client reconciles it. */
+export declare const CloudRecordCollectionSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export type CloudRecordCollection = z.infer<typeof CloudRecordCollectionSchema>;
+export declare const MemoryStorageSnapshotSchema: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+export type MemoryStorageSnapshot = z.infer<typeof MemoryStorageSnapshotSchema>;
+export declare const AdapterSelectionRequestSchema: z.ZodObject<{
+    ownerKind: z.ZodEnum<{
+        record: "record";
+        manifest: "manifest";
+    }>;
+    ownerId: z.ZodString;
+    allowedAdapters: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    preferred: z.ZodOptional<z.ZodObject<{
+        adapterId: z.ZodString;
+        source: z.ZodEnum<{
+            descriptor: "descriptor";
+            policy: "policy";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AdapterSelectionRequest = z.infer<typeof AdapterSelectionRequestSchema>;
+export declare const ManifestDataSourceSchema: z.ZodEnum<{
+    "user-localdb": "user-localdb";
+    "project-file": "project-file";
+    "cloud-api": "cloud-api";
+}>;
+export type ManifestDataSource = z.infer<typeof ManifestDataSourceSchema>;
+//# sourceMappingURL=adapter-config.d.ts.map

package/dist/schemas/adapter-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-config.d.ts","sourceRoot":"","sources":["../../src/schemas/adapter-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAE5B;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,wCAAoC,CAAC;AAC5E,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,+DAA+D;AAC/D,eAAO,MAAM,0BAA0B,wCAAoC,CAAC;AAC5E,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,kHAAkH;AAClH,eAAO,MAAM,+BAA+B,cAAc,CAAC;AAC3D,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF,2FAA2F;AAC3F,eAAO,MAAM,2BAA2B,wCAAoC,CAAC;AAC7E,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAGhF,eAAO,MAAM,2BAA2B,kEAA0D,CAAC;AAEnG,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;iBAIxC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AACpF,eAAO,MAAM,wBAAwB;;;;EAAwD,CAAC;AAC9F,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}