@vibesdotdev/storage 0.0.1 → 1.0.0-rc.3

package/dist/record/merge.d.ts

@@ -0,0 +1,21 @@
+import type { CreateInput, StorageRecordInterface } from '../interfaces/record/interface.ts';
+/** Canonical Storage optimistic compare-and-set retry budget (matching LocalDB document updates). */
+export declare const RECORD_MERGE_ATTEMPTS = 64;
+/** Options for {@link mergeRecord}. */
+type RecordMergeOptions = {
+    /** Maximum optimistic compare-and-set attempts before refusing with a retryable OptimisticLockError. */
+    readonly maxAttempts?: number;
+};
+/**
+ * Storage-owned optimistic read-merge-write for a single record row.
+ *
+ * Reads the current row (or `null` when absent), computes the next state via
+ * `transform`, and atomically creates or updates the row guarded by the exact
+ * field state read. Concurrent creates or updates retry up to the Storage
+ * owner's concurrency budget (`RECORD_MERGE_ATTEMPTS`) and throw a retryable
+ * `OptimisticLockError` (`CONFLICT`, `reason: 'record-precondition-conflict'`)
+ * if contention does not converge.
+ */
+export declare function mergeRecord<T>(record: StorageRecordInterface<T>, id: string, transform: (current: NoInfer<T> | null) => CreateInput<NoInfer<T>> | NoInfer<T> | Promise<CreateInput<NoInfer<T>> | NoInfer<T>>, options?: RecordMergeOptions): Promise<T>;
+export {};
+//# sourceMappingURL=merge.d.ts.map

package/dist/record/merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../src/record/merge.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,sBAAsB,EAAe,MAAM,mCAAmC,CAAC;AAO1G,qGAAqG;AACrG,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC,uCAAuC;AACvC,KAAK,kBAAkB,GAAG;IACzB,wGAAwG;IACxG,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAyDF;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAClC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC,EACjC,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,CACV,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,KACtB,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,EACzF,OAAO,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,CAAC,CAAC,CAyFZ"}

package/dist/record/merge.js

@@ -0,0 +1,147 @@
+import { CapabilityError, settle } from '@vibesdotdev/kernel';
+import * as z from 'zod/v4';
+import { ZodNodeSchema } from "../schemas/record/columns.js";
+import { parseAdapterInput } from "../adapters/parse-adapter-input.js";
+import { OptimisticLockError } from "./base.js";
+/** Canonical Storage optimistic compare-and-set retry budget (matching LocalDB document updates). */
+export const RECORD_MERGE_ATTEMPTS = 64;
+function isFieldMap(value) {
+    return value instanceof Object && !Array.isArray(value);
+}
+const RecordFieldsViewSchema = z.custom((value) => isFieldMap(value));
+function fieldsOf(tableName, value) {
+    return parseAdapterInput(RecordFieldsViewSchema, value, {
+        message: 'A storage record value must be a field map.',
+        code: 'INVALID_INPUT',
+        reason: 'record-value-invalid',
+        details: { tableName }
+    });
+}
+function createInputOf(tableName, value) {
+    return parseAdapterInput(z.custom((candidate) => isFieldMap(candidate)), value, {
+        message: 'A storage record create input must be a field map.',
+        code: 'INVALID_INPUT',
+        reason: 'record-value-invalid',
+        details: { tableName }
+    });
+}
+function updateInputOf(tableName, value) {
+    return parseAdapterInput(z.custom((candidate) => isFieldMap(candidate)), value, {
+        message: 'A storage record update input must be a field map.',
+        code: 'INVALID_INPUT',
+        reason: 'record-value-invalid',
+        details: { tableName }
+    });
+}
+/** The declared object field schemas of a record schema, unwrapping outer refinements or pipes. */
+function schemaFieldsOf(schema) {
+    let current = schema;
+    for (let depth = 0; depth < 8 && current; depth++) {
+        const parsed = ZodNodeSchema.safeParse(current._zod);
+        if (!parsed.success)
+            break;
+        if (parsed.data.def.type === 'object' && parsed.data.def.shape) {
+            return parsed.data.def.shape;
+        }
+        current = parsed.data.def.innerType ?? parsed.data.def.in;
+    }
+    return {};
+}
+/**
+ * Storage-owned optimistic read-merge-write for a single record row.
+ *
+ * Reads the current row (or `null` when absent), computes the next state via
+ * `transform`, and atomically creates or updates the row guarded by the exact
+ * field state read. Concurrent creates or updates retry up to the Storage
+ * owner's concurrency budget (`RECORD_MERGE_ATTEMPTS`) and throw a retryable
+ * `OptimisticLockError` (`CONFLICT`, `reason: 'record-precondition-conflict'`)
+ * if contention does not converge.
+ */
+export async function mergeRecord(record, id, transform, options) {
+    const maxAttempts = options?.maxAttempts ?? RECORD_MERGE_ATTEMPTS;
+    if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+        throw new CapabilityError('Record merge attempt budget must be a positive integer.', 'INVALID_INPUT', {
+            reason: 'record-merge-attempts-invalid',
+            retryable: false
+        });
+    }
+    if (!record.supportsConditionalWrites) {
+        const adapterId = record.getAdapterId();
+        throw new CapabilityError(`Storage adapter '${adapterId}' does not support atomic conditional record writes.`, 'UNAVAILABLE', {
+            reason: 'record-conditional-write-unsupported',
+            retryable: false,
+            details: { adapterId, tableName: record.tableName }
+        });
+    }
+    const schemaFields = schemaFieldsOf(record.schema);
+    const nullableAndOptional = new Set();
+    for (const [field, fieldSchema] of Object.entries(schemaFields)) {
+        if (fieldSchema.safeParse(undefined).success && fieldSchema.safeParse(null).success) {
+            nullableAndOptional.add(field);
+        }
+    }
+    let lastConflict;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        const existing = await record.get(id);
+        if (existing === null) {
+            const created = await transform(null);
+            const input = { ...fieldsOf(record.tableName, created), [record.primaryKey]: id };
+            const inserted = await settle(() => record.create(createInputOf(record.tableName, input)));
+            if (inserted.ok)
+                return inserted.value;
+            if (inserted.cause instanceof CapabilityError &&
+                (inserted.cause.reason === 'record-identity-conflict' || inserted.cause.reason === 'record-insert-conflict')) {
+                lastConflict = new OptimisticLockError(record.tableName, id, { [record.primaryKey]: { isNull: true } }, inserted.cause);
+                continue;
+            }
+            throw inserted.cause;
+        }
+        const baseline = structuredClone(fieldsOf(record.tableName, existing));
+        const candidate = fieldsOf(record.tableName, await transform(structuredClone(existing)));
+        const keys = new Set([
+            ...Object.keys(schemaFields),
+            ...Object.keys(baseline),
+            ...Object.keys(candidate)
+        ]);
+        keys.delete(record.primaryKey);
+        const where = {};
+        const patch = {};
+        for (const key of keys) {
+            const previous = baseline[key];
+            if (previous === undefined) {
+                where[key] = { eq: undefined };
+            }
+            else if (previous === null && nullableAndOptional.has(key)) {
+                where[key] = { eq: null, ne: undefined };
+            }
+            else {
+                where[key] = { eq: previous };
+            }
+            if (Object.hasOwn(candidate, key) && candidate[key] !== undefined) {
+                patch[key] = candidate[key];
+            }
+            else if (Object.hasOwn(baseline, key) && baseline[key] !== undefined) {
+                patch[key] = undefined;
+            }
+        }
+        const updated = await settle(() => record.update(id, updateInputOf(record.tableName, patch), { where }));
+        if (updated.ok)
+            return updated.value;
+        const cause = updated.cause;
+        if (cause instanceof OptimisticLockError) {
+            lastConflict = cause;
+            continue;
+        }
+        if (cause instanceof CapabilityError && cause.reason === 'record-precondition-conflict') {
+            lastConflict = new OptimisticLockError(record.tableName, id, where, cause);
+            continue;
+        }
+        if (cause instanceof CapabilityError && cause.reason === 'record-absent' && !(await record.exists(id))) {
+            lastConflict = new OptimisticLockError(record.tableName, id, where, cause);
+            continue;
+        }
+        throw cause;
+    }
+    throw lastConflict ?? new OptimisticLockError(record.tableName, id, {});
+}
+//# sourceMappingURL=merge.js.map

package/dist/record/merge.js.map

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

package/dist/record/relations.d.ts

@@ -0,0 +1,23 @@
+import { type RuntimeRef } from '@vibesdotdev/kernel';
+import type { IncludeRelations } from '../interfaces/record/index.ts';
+import type { StorageRelation } from '../schemas/record/relation.ts';
+/** What a record hands the loader: its kind id, primary key, declared relations and the runtime its targets resolve on. */
+export interface RecordRelationOwner {
+    readonly recordKind: string;
+    readonly primaryKey: string;
+    readonly relations: Readonly<Record<string, StorageRelation>>;
+    /** The record's runtime; a record built without one refuses a non-empty include `UNAVAILABLE`. */
+    readonly runtime: RuntimeRef | undefined;
+}
+/**
+ * The relations `include` asks for, each with the include handed to its
+ * target. `[]`, `{}` and `{ name: false }` ask for none.
+ */
+export declare function requestedRelations(include: IncludeRelations | undefined): Array<[string, IncludeRelations | undefined]>;
+/**
+ * Load each relation `include` names onto `record` (the same object). A name
+ * the owner declares no relation for refuses `INVALID_INPUT`
+ * `record-relation-unknown`, checked for every name before any loads.
+ */
+export declare function loadRecordRelations<Row>(owner: RecordRelationOwner, record: Row, include: IncludeRelations | undefined): Promise<Row>;
+//# sourceMappingURL=relations.d.ts.map

package/dist/record/relations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations.d.ts","sourceRoot":"","sources":["../../src/record/relations.ts"],"names":[],"mappings":"AASA,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAA0B,MAAM,+BAA+B,CAAC;AAE9F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAIrE,2HAA2H;AAC3H,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;IAC9D,kGAAkG;IAClG,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,CAAC;CACzC;AAQD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,CAAC,CAAC,CAOvH;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,KAAK,EAAE,mBAAmB,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB,GAAG,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,CAyB3I"}

package/dist/record/relations.js

@@ -0,0 +1,164 @@
+/**
+ * Relation loading for every `storage/record` implementation. `include` names
+ * relations the descriptor declares; each loads from its target record,
+ * resolved by kind (`storage/record` with the relation's `target` id) on the
+ * record's runtime, so the target's own adapter answers. An include that
+ * cannot be honoured refuses typed: it never answers as if the relation were
+ * empty.
+ */
+import * as z from 'zod/v4';
+import { CapabilityError } from '@vibesdotdev/kernel';
+import { outcomeOf } from "../utils/failure-of.js";
+/** A record value seen as its field map: the same object, so each loaded relation lands on it. */
+const RecordFieldsViewSchema = z.custom((value) => value instanceof Object && !Array.isArray(value));
+/**
+ * The relations `include` asks for, each with the include handed to its
+ * target. `[]`, `{}` and `{ name: false }` ask for none.
+ */
+export function requestedRelations(include) {
+    if (include === undefined)
+        return [];
+    const single = z.string().safeParse(include);
+    if (single.success)
+        return [[single.data, undefined]];
+    if (Array.isArray(include))
+        return include.map((name) => [name, undefined]);
+    return Object.entries(include).flatMap(([name, wanted]) => wanted === false || wanted === undefined ? [] : [[name, wanted === true ? undefined : wanted]]);
+}
+/**
+ * Load each relation `include` names onto `record` (the same object). A name
+ * the owner declares no relation for refuses `INVALID_INPUT`
+ * `record-relation-unknown`, checked for every name before any loads.
+ */
+export async function loadRecordRelations(owner, record, include) {
+    const requested = requestedRelations(include);
+    if (requested.length === 0)
+        return record;
+    const declared = requested.map(([name, nested]) => {
+        const relation = Object.hasOwn(owner.relations, name) ? owner.relations[name] : undefined;
+        if (relation)
+            return [name, relation, nested];
+        throw new CapabilityError(`Storage record '${owner.recordKind}' declares no relation '${name}'.`, 'INVALID_INPUT', {
+            reason: 'record-relation-unknown',
+            retryable: false,
+            details: { recordKind: owner.recordKind, relation: name, declared: Object.keys(owner.relations) }
+        });
+    });
+    const runtime = owner.runtime;
+    if (!runtime) {
+        throw new CapabilityError(`Storage record '${owner.recordKind}' has no runtime to resolve relation targets on.`, 'UNAVAILABLE', {
+            reason: 'record-relation-runtime-missing',
+            retryable: false,
+            details: { recordKind: owner.recordKind, relations: declared.map(([name]) => name) }
+        });
+    }
+    const fields = RecordFieldsViewSchema.parse(record);
+    for (const [name, relation, nested] of declared) {
+        fields[name] = await loadRelation({ owner, runtime, fields, name, relation }, nested);
+    }
+    return record;
+}
+/**
+ * Load one declared relation. `foreignKey` is the linking field: on this
+ * record for belongs_to, on the target for has_one/has_many, on the `through`
+ * junction for many_to_many (whose `targetKey` holds the target's id). An
+ * unset linking value is a real empty relation; `nested` is the include
+ * handed to the target.
+ */
+async function loadRelation(load, nested) {
+    const { owner, fields, relation } = load;
+    switch (relation.type) {
+        case 'belongs_to': {
+            const foreignId = stringField(fields, relationKey(load, 'foreignKey'));
+            if (!foreignId)
+                return null;
+            return (await relatedRecord(load, relation.target)).get(foreignId, { include: nested });
+        }
+        case 'has_one':
+        case 'has_many': {
+            const foreignKey = relationKey(load, 'foreignKey');
+            const ownId = stringField(fields, owner.primaryKey);
+            if (!ownId)
+                return relation.type === 'has_one' ? null : [];
+            const target = await relatedRecord(load, relation.target);
+            const where = { [foreignKey]: ownId };
+            if (relation.type === 'has_one')
+                return target.findFirst({ where, include: nested });
+            return (await target.list({ where, include: nested })).items;
+        }
+        case 'many_to_many':
+            return loadManyToMany(load, nested);
+        default: {
+            const unreachable = relation.type;
+            throw new CapabilityError(`Relation '${load.name}' has an unsupported type.`, 'INVALID_INPUT', {
+                reason: 'record-relation-type-unsupported',
+                retryable: false,
+                details: { recordKind: owner.recordKind, relation: load.name, type: String(unreachable) }
+            });
+        }
+    }
+}
+/**
+ * many_to_many through the `through` junction record: its rows whose
+ * `foreignKey` holds this row's id name, by `targetKey`, the target rows.
+ */
+async function loadManyToMany(load, nested) {
+    const { owner, fields, name, relation } = load;
+    const through = relation.through;
+    if (!through) {
+        throw new CapabilityError(`Relation '${name}' (many_to_many) on '${owner.recordKind}' declares no 'through' junction.`, 'INVALID_INPUT', {
+            reason: 'record-relation-through-missing',
+            retryable: false,
+            details: { recordKind: owner.recordKind, relation: name, type: relation.type }
+        });
+    }
+    const foreignKey = relationKey(load, 'foreignKey');
+    const targetKey = relationKey(load, 'targetKey');
+    const ownId = stringField(fields, owner.primaryKey);
+    if (!ownId)
+        return [];
+    const junction = await relatedRecord(load, through);
+    const links = (await junction.list({ where: { [foreignKey]: ownId } })).items;
+    const targetIds = new Set();
+    for (const link of links) {
+        const targetId = stringField(link, targetKey);
+        if (!targetId) {
+            throw new CapabilityError(`A '${through}' junction row for relation '${name}' holds no '${targetKey}'.`, 'INTERNAL', {
+                reason: 'record-relation-junction-row-invalid',
+                retryable: false,
+                details: { recordKind: owner.recordKind, relation: name, through, targetKey }
+            });
+        }
+        targetIds.add(targetId);
+    }
+    if (targetIds.size === 0)
+        return [];
+    return (await relatedRecord(load, relation.target)).getMany([...targetIds], { include: nested });
+}
+/** A relation's declared linking field; one its type reads but it does not declare refuses `INVALID_INPUT`. */
+function relationKey({ owner, name, relation }, key) {
+    const value = relation[key];
+    if (value)
+        return value;
+    throw new CapabilityError(`Relation '${name}' (${relation.type}) on '${owner.recordKind}' declares no '${key}'.`, 'INVALID_INPUT', {
+        reason: 'record-relation-key-missing',
+        retryable: false,
+        details: { recordKind: owner.recordKind, relation: name, type: relation.type, key }
+    });
+}
+/** A record the relation reads (its target or junction) resolved by kind; one that cannot be resolved refuses `UNAVAILABLE` with its cause. */
+async function relatedRecord({ owner, runtime, name }, id) {
+    const resolved = await outcomeOf(() => runtime.query('storage/record').withId(id).enabled().resolve());
+    if (resolved.ok)
+        return resolved.value;
+    throw new CapabilityError(`Relation '${name}' on '${owner.recordKind}' cannot resolve its record '${id}'.`, 'UNAVAILABLE', {
+        reason: 'record-relation-target-unavailable',
+        details: { recordKind: owner.recordKind, relation: name, target: id },
+        cause: resolved.failure
+    });
+}
+function stringField(fields, field) {
+    const value = z.string().min(1).safeParse(fields[field]);
+    return value.success ? value.data : null;
+}
+//# sourceMappingURL=relations.js.map

package/dist/record/relations.js.map

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

package/dist/record/revision.d.ts

@@ -0,0 +1,5 @@
+import type { StorageRecordInterface } from '../interfaces/record/interface.ts';
+import type { RecordRevisionAccess } from '../schemas/record/revision.ts';
+/** Require the selected record owner's revision capability; never substitute body or timestamp reads. */
+export declare function recordRevisions<Value>(record: Pick<StorageRecordInterface<Value>, 'revisions'>): RecordRevisionAccess<Value>;
+//# sourceMappingURL=revision.d.ts.map

package/dist/record/revision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revision.d.ts","sourceRoot":"","sources":["../../src/record/revision.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAChF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAE1E,yGAAyG;AACzG,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,sBAAsB,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAM5H"}

package/dist/record/revision.js

@@ -0,0 +1,11 @@
+import { CapabilityError } from '@vibesdotdev/kernel';
+/** Require the selected record owner's revision capability; never substitute body or timestamp reads. */
+export function recordRevisions(record) {
+    const revisions = record.revisions;
+    if (!revisions)
+        throw new CapabilityError('This record does not provide persisted revisions.', 'UNAVAILABLE', {
+            reason: 'record-revision-unavailable', retryable: false
+        });
+    return revisions;
+}
+//# sourceMappingURL=revision.js.map

package/dist/record/revision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"revision.js","sourceRoot":"","sources":["../../src/record/revision.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAItD,yGAAyG;AACzG,MAAM,UAAU,eAAe,CAAQ,MAAwD;IAC9F,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;IACnC,IAAI,CAAC,SAAS;QAAE,MAAM,IAAI,eAAe,CAAC,mDAAmD,EAAE,aAAa,EAAE;YAC7G,MAAM,EAAE,6BAA6B,EAAE,SAAS,EAAE,KAAK;SACvD,CAAC,CAAC;IACH,OAAO,SAAS,CAAC;AAClB,CAAC"}

package/dist/record/schema-coordination.client.d.ts

@@ -0,0 +1,16 @@
+/** Runtime-owned record DDL coordination; physical files use LocalDB's pool owner. */
+import { type RuntimeRef } from '@vibesdotdev/kernel';
+import { BaseRuntimeClient } from '@vibesdotdev/kernel/client';
+import type { SqlDatabaseHandle } from '../interfaces/adapter.ts';
+type SchemaDatabaseIdentity = Pick<SqlDatabaseHandle, 'path'>;
+export declare class SchemaCoordinationClient extends BaseRuntimeClient {
+    /** Handles without a physical path identify independent databases. */
+    private readonly memoryTurns;
+    initializeSchema(db: SchemaDatabaseIdentity, operation: () => Promise<void>): Promise<void>;
+    protected onDispose(): Promise<void>;
+}
+export declare const schemaCoordinationPlugin: import("@vibesdotdev/kernel").RuntimePlugin;
+/** Bare record consumers retain lazy composition; the kernel owns the instance. */
+export declare function resolveSchemaCoordination(runtime: RuntimeRef): Promise<SchemaCoordinationClient>;
+export {};
+//# sourceMappingURL=schema-coordination.client.d.ts.map

package/dist/record/schema-coordination.client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-coordination.client.d.ts","sourceRoot":"","sources":["../../src/record/schema-coordination.client.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,OAAO,EAA+C,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACnG,OAAO,EACN,iBAAiB,EAEjB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,KAAK,sBAAsB,GAAG,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC;AAI9D,qBAAa,wBAAyB,SAAQ,iBAAiB;IAC9D,sEAAsE;IACtE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoD;IAE1E,gBAAgB,CAAC,EAAE,EAAE,sBAAsB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;cAuBxE,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CAInD;AAED,eAAO,MAAM,wBAAwB,6CAUnC,CAAC;AAEH,mFAAmF;AACnF,wBAAsB,yBAAyB,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAQtG"}

package/dist/record/schema-coordination.client.js

@@ -0,0 +1,59 @@
+/** Runtime-owned record DDL coordination; physical files use LocalDB's pool owner. */
+import { createRuntimePlugin } from '@vibesdotdev/kernel';
+import { BaseRuntimeClient, getVibesClient, tryGetVibesClient, runtimeClientPlugin, RuntimeClientDescriptorSchema } from '@vibesdotdev/kernel/client';
+const CLIENT_ID = 'storage.schema-coordination';
+export class SchemaCoordinationClient extends BaseRuntimeClient {
+    /** Handles without a physical path identify independent databases. */
+    memoryTurns = new Map();
+    async initializeSchema(db, operation) {
+        if (db.path !== undefined && db.path !== ':memory:' && db.path !== '') {
+            // Match LocalDB's explicit shared-pool contract. Multiple roots opening
+            // the same files must be handed the same pool by their composition root.
+            const pools = this.runtime.query('localdb/pool');
+            const id = pools.withId('shared').descriptors().length > 0 ? 'shared' : 'pool';
+            const pool = await pools.withId(id).resolve();
+            return pool.withDatabasePathLock(db.path, operation);
+        }
+        const previous = this.memoryTurns.get(db) ?? Promise.resolve();
+        const turn = Promise.withResolvers();
+        const current = previous.then(() => turn.promise);
+        this.memoryTurns.set(db, current);
+        await previous;
+        try {
+            await operation();
+        }
+        finally {
+            turn.resolve();
+            if (this.memoryTurns.get(db) === current)
+                this.memoryTurns.delete(db);
+        }
+    }
+    async onDispose() {
+        await Promise.all(this.memoryTurns.values());
+        this.memoryTurns.clear();
+    }
+}
+export const schemaCoordinationPlugin = createRuntimePlugin({
+    id: 'storage.schema-coordination',
+    name: 'Storage Schema Coordination',
+    descriptors: [RuntimeClientDescriptorSchema.parse({
+            id: CLIENT_ID, kind: 'runtime/client', name: 'Storage Schema Coordination'
+        })],
+    async onRegister(runtime) {
+        if (!runtime.hasKind('runtime/client'))
+            await runtime.registerPlugin(runtimeClientPlugin);
+        runtime.registerLoader('runtime/client', CLIENT_ID, async () => ({ impl: SchemaCoordinationClient }));
+    }
+});
+/** Bare record consumers retain lazy composition; the kernel owns the instance. */
+export async function resolveSchemaCoordination(runtime) {
+    const warm = tryGetVibesClient(CLIENT_ID, runtime);
+    if (warm)
+        return warm;
+    if (!runtime.hasKind('runtime/client')
+        || runtime.query('runtime/client').withId(CLIENT_ID).descriptors().length === 0) {
+        await runtime.registerPlugin(schemaCoordinationPlugin);
+    }
+    return getVibesClient(CLIENT_ID, runtime);
+}
+//# sourceMappingURL=schema-coordination.client.js.map

package/dist/record/schema-coordination.client.js.map

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

package/dist/record/storage.record-delivery.reconcile.descriptor.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Record Delivery Reconcile Job Descriptor (D-RC11)
+ *
+ * The live half of durable record delivery. `create()` claims each record's
+ * delivery job; when that claim fails after the row committed (the queue was
+ * unreachable, the writer exited mid-call), this Workers-scheduled job claims
+ * it again while the consumer is running. Bound: a record whose create-time
+ * claim failed is claimed within one schedule period (60 s) plus the queue's
+ * pickup latency. Workers owns the schedule (D19); nothing here is a timer.
+ */
+import * as z from 'zod/v4';
+export declare const RECORD_DELIVERY_RECONCILE_JOB_ID = "storage.record-delivery.reconcile";
+/** The reconcile period in cron form, and the same bound in milliseconds. */
+export declare const RECORD_DELIVERY_RECONCILE_SCHEDULE = "* * * * *";
+export declare const RECORD_DELIVERY_RECONCILE_PERIOD_MS = 60000;
+export declare const RecordDeliveryReconcileOutputSchema: z.ZodObject<{
+    records: z.ZodArray<z.ZodObject<{
+        recordKind: z.ZodString;
+        job: z.ZodString;
+        pending: z.ZodNumber;
+        enqueued: z.ZodNumber;
+        alreadyActive: z.ZodNumber;
+        restarted: z.ZodNumber;
+        terminal: z.ZodNumber;
+        failed: z.ZodNumber;
+        skipped: z.ZodOptional<z.ZodObject<{
+            reason: z.ZodString;
+            condition: z.ZodString;
+        }, z.core.$strip>>;
+        error: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type RecordDeliveryReconcileOutput = z.infer<typeof RecordDeliveryReconcileOutputSchema>;
+export declare const recordDeliveryReconcileJobDescriptor: {
+    kind: "workers/job";
+    id: string;
+    name: string;
+    description: string;
+    queue: string;
+    dispatch: "background";
+    type: "scheduled";
+    schedule: string;
+    retries: {
+        maxAttempts: number;
+        backoff: "fixed";
+        delay: number;
+    };
+    timeout: number;
+    hardware: readonly ["consumer"];
+    schemas: {
+        input: z.ZodPrefault<z.ZodObject<{}, z.core.$strip>>;
+        output: z.ZodObject<{
+            records: z.ZodArray<z.ZodObject<{
+                recordKind: z.ZodString;
+                job: z.ZodString;
+                pending: z.ZodNumber;
+                enqueued: z.ZodNumber;
+                alreadyActive: z.ZodNumber;
+                restarted: z.ZodNumber;
+                terminal: z.ZodNumber;
+                failed: z.ZodNumber;
+                skipped: z.ZodOptional<z.ZodObject<{
+                    reason: z.ZodString;
+                    condition: z.ZodString;
+                }, z.core.$strip>>;
+                error: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    };
+    tags: string[];
+    enabled: true;
+};
+export default recordDeliveryReconcileJobDescriptor;
+//# sourceMappingURL=storage.record-delivery.reconcile.descriptor.d.ts.map

package/dist/record/storage.record-delivery.reconcile.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.record-delivery.reconcile.descriptor.d.ts","sourceRoot":"","sources":["../../src/record/storage.record-delivery.reconcile.descriptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAG5B,eAAO,MAAM,gCAAgC,sCAAsC,CAAC;AAEpF,6EAA6E;AAC7E,eAAO,MAAM,kCAAkC,cAAc,CAAC;AAC9D,eAAO,MAAM,mCAAmC,QAAS,CAAC;AAE1D,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;;iBAgB9C,CAAC;AACH,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mCAAmC,CAAC,CAAC;AAEhG,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoB/C,CAAC;AAEH,eAAe,oCAAoC,CAAC"}

package/dist/record/storage.record-delivery.reconcile.descriptor.js

@@ -0,0 +1,54 @@
+/**
+ * Record Delivery Reconcile Job Descriptor (D-RC11)
+ *
+ * The live half of durable record delivery. `create()` claims each record's
+ * delivery job; when that claim fails after the row committed (the queue was
+ * unreachable, the writer exited mid-call), this Workers-scheduled job claims
+ * it again while the consumer is running. Bound: a record whose create-time
+ * claim failed is claimed within one schedule period (60 s) plus the queue's
+ * pickup latency. Workers owns the schedule (D19); nothing here is a timer.
+ */
+import * as z from 'zod/v4';
+import { createRuntimeAsset } from '@vibesdotdev/kernel';
+export const RECORD_DELIVERY_RECONCILE_JOB_ID = 'storage.record-delivery.reconcile';
+/** The reconcile period in cron form, and the same bound in milliseconds. */
+export const RECORD_DELIVERY_RECONCILE_SCHEDULE = '* * * * *';
+export const RECORD_DELIVERY_RECONCILE_PERIOD_MS = 60_000;
+export const RecordDeliveryReconcileOutputSchema = z.object({
+    records: z.array(z.object({
+        recordKind: z.string(),
+        job: z.string(),
+        pending: z.number().int().nonnegative(),
+        enqueued: z.number().int().nonnegative(),
+        alreadyActive: z.number().int().nonnegative(),
+        restarted: z.number().int().nonnegative(),
+        terminal: z.number().int().nonnegative(),
+        failed: z.number().int().nonnegative(),
+        /** The kind's delivery gate held this pass; nothing was claimed. */
+        skipped: z.object({ reason: z.string(), condition: z.string() }).optional(),
+        error: z.string().optional()
+    }))
+});
+export const recordDeliveryReconcileJobDescriptor = createRuntimeAsset({
+    kind: 'workers/job',
+    id: RECORD_DELIVERY_RECONCILE_JOB_ID,
+    name: 'Record Delivery Reconcile',
+    description: 'Claim the delivery job of every storage record still pending delivery',
+    // The queue the consumer's maintenance worker serves.
+    queue: 'maintenance-jobs',
+    dispatch: 'background',
+    type: 'scheduled',
+    schedule: RECORD_DELIVERY_RECONCILE_SCHEDULE,
+    // One attempt: the next scheduled run is the retry.
+    retries: { maxAttempts: 1, backoff: 'fixed', delay: 0 },
+    timeout: 55_000,
+    hardware: ['consumer'],
+    schemas: {
+        input: z.object({}).prefault({}),
+        output: RecordDeliveryReconcileOutputSchema
+    },
+    tags: ['storage', 'delivery', 'reconcile'],
+    enabled: true
+});
+export default recordDeliveryReconcileJobDescriptor;
+//# sourceMappingURL=storage.record-delivery.reconcile.descriptor.js.map