@feltdb/core 0.8.3 → 0.8.4

package/dist/cli/commands.js

@@ -293,8 +293,11 @@ async function handleAi(args) {
         if (stored) {
             const client = proposalService();
             const readiness = await client.status(stored.id);
+            // Coded like every other refusal this command can produce
+            // (SOURCE_SYNC_CONFLICT, REPOSITORY_AUTHORITY_REQUIRED), so a caller can
+            // tell a stale proposal from a failed apply without reading the prose.
             if (readiness.blockers.length)
-                throw new Error(`Cannot apply Proposal ${stored.id}. Proposal is stale: ${readiness.blockers.join(', ')}. Proposal contract: ${stored.base_contract_hash}. Current contract: ${readiness.current_contract_hash}. Regenerate the Proposal before applying.`);
+                throw new Error(`STALE_PROPOSAL: Cannot apply Proposal ${stored.id}. Proposal is stale: ${readiness.blockers.join(', ')}. Proposal contract: ${stored.base_contract_hash}. Current contract: ${readiness.current_contract_hash}. Regenerate the Proposal before applying.`);
             if (!stored.preview_id)
                 throw new Error(`Cannot apply Proposal ${stored.id}. A current preview is required.`);
             await client.getPreview(stored.preview_id);

package/dist/cli/provisioning-neutrality.js

@@ -0,0 +1,79 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+function canonicalMode(input) {
+    const value = (input.mode || input.deploymentMode || input.runtime || (input.url || input.endpoint ? 'remote' : 'browser')).toLowerCase();
+    if (value === 'browser')
+        return 'browser';
+    if (value === 'local' || value === 'node')
+        return 'local';
+    if (value === 'remote' || value === 'self-hosted' || value === 'managed')
+        return 'remote';
+    throw new Error(`Unsupported FeltDB provisioning mode "${value}"`);
+}
+function sortRecord(record) {
+    if (!record)
+        return undefined;
+    return Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b)));
+}
+export function canonicalizeProvisioningConfiguration(input) {
+    const mode = canonicalMode(input);
+    const credentialReference = input.credentialReference?.trim();
+    const hasToken = !!input.token;
+    return {
+        deployment: {
+            mode,
+            endpoint: input.endpoint || input.url || undefined,
+            localDataPath: input.localDataPath || input.path || undefined,
+        },
+        application: {
+            id: input.applicationId || undefined,
+            namespace: input.namespace || undefined,
+            environment: input.environment || undefined,
+        },
+        credentials: {
+            present: hasToken || !!credentialReference,
+            type: credentialReference ? 'reference' : hasToken ? 'token' : 'none',
+            reference: credentialReference || undefined,
+        },
+        capabilities: sortRecord(input.capabilities),
+    };
+}
+export function provisioningConfigurationsEquivalent(left, right) {
+    return JSON.stringify(canonicalizeProvisioningConfiguration(left)) === JSON.stringify(canonicalizeProvisioningConfiguration(right));
+}
+export function provisioningConfigurationHash(input) {
+    const canonical = canonicalizeProvisioningConfiguration({ ...input, token: input.token ? '<present>' : undefined });
+    return crypto.createHash('sha256').update(JSON.stringify(canonical)).digest('hex');
+}
+export function writeDeploymentConfiguration(projectDir, input) {
+    const canonical = canonicalizeProvisioningConfiguration(input);
+    fs.mkdirSync(projectDir, { recursive: true });
+    fs.mkdirSync(path.join(projectDir, '.feltdb'), { recursive: true });
+    fs.writeFileSync(path.join(projectDir, 'feltdb.config.json'), `${JSON.stringify({
+        mode: canonical.deployment.mode,
+        namespace: canonical.application.namespace,
+        environment: canonical.application.environment,
+        applicationId: canonical.application.id,
+        url: canonical.deployment.endpoint,
+        path: canonical.deployment.localDataPath,
+        capabilities: canonical.capabilities || {},
+    }, null, 2)}\n`);
+    const envLines = [
+        '# Generated by feltdb provisioning. Do not commit secrets.',
+        `FELTDB_MODE=${canonical.deployment.mode}`,
+        canonical.deployment.endpoint ? `FELTDB_URL=${canonical.deployment.endpoint}` : undefined,
+        canonical.deployment.localDataPath ? `FELTDB_PATH=${canonical.deployment.localDataPath}` : undefined,
+        canonical.application.id ? `FELTDB_APPLICATION_ID=${canonical.application.id}` : undefined,
+        canonical.application.namespace ? `FELTDB_NAMESPACE=${canonical.application.namespace}` : undefined,
+        canonical.application.environment ? `FELTDB_ENVIRONMENT=${canonical.application.environment}` : undefined,
+        canonical.credentials.type === 'reference' && canonical.credentials.reference ? `FELTDB_CREDENTIAL_REFERENCE=${canonical.credentials.reference}` : undefined,
+        '',
+    ].filter((line) => line !== undefined);
+    fs.writeFileSync(path.join(projectDir, '.env.local'), envLines.join('\n'), { mode: 0o600 });
+    fs.writeFileSync(path.join(projectDir, '.feltdb', 'provisioning.json'), `${JSON.stringify({
+        ...canonical,
+        configurationHash: provisioningConfigurationHash(input),
+    }, null, 2)}\n`, { mode: 0o600 });
+    return canonical;
+}

package/dist/collection.d.ts

@@ -97,6 +97,8 @@ export declare class Collection<T> {
      * Returns cached results (live-updated).
      */
     all(): Promise<T[]>;
+    /** List records through the canonical application collection API. */
+    list(): Promise<T[]>;
     /**
      * Find records whose fields match the supplied query.
      *
@@ -112,6 +114,8 @@ export declare class Collection<T> {
      * `lastQueryPlan()` reports which path ran.
      */
     find(query?: Partial<T>): Promise<T[]>;
+    /** Query records by field equality through the canonical application API. */
+    query(query?: Partial<T>): Promise<T[]>;
     /**
      * How the most recent `find` was answered.
      *
@@ -171,6 +175,8 @@ export declare class Collection<T> {
      * Automatically initializes __version to 1 for durable atomic transitions.
      */
     insert(data: Partial<T>, id?: string | number): Promise<string>;
+    /** Put a record through the canonical application collection API. */
+    put(data: Partial<T>, id?: string | number): Promise<string>;
     /**
      * Update a record in this collection.
      */
@@ -182,6 +188,10 @@ export declare class Collection<T> {
      * The version check and update happen atomically at the backend boundary,
      * ensuring exactly one writer succeeds when multiple writers race.
      *
+     * A runtime without a dedicated compare-and-set carries the same fence
+     * through its atomic transaction, so this means the same thing on the file
+     * runtime as it does against a managed authority.
+     *
      * @param id Record identifier
      * @param expectedVersion The version you observed when you read this record
      * @param updates Fields to update (does not include __version; version is auto-incremented)
@@ -217,9 +227,41 @@ export declare class Collection<T> {
      * Check if a record exists.
      */
     exists(id: string | number): Promise<boolean>;
+    /**
+     * Split a storage key back into the collection and record it addresses.
+     *
+     * The transaction contract is expressed in collections and ids rather than
+     * in storage keys, so a helper that holds a key has to name the record the
+     * same way the authority does.
+     */
+    private addressOf;
+    /**
+     * The runtime's atomic transaction, used as the conditional-create surface.
+     *
+     * Returns the same shape a runtime's own `putIfAbsent` returns, so the caller
+     * above cannot tell which route it took. A refusal that is a lost race is
+     * resolved by reading the record the winner wrote; anything else -- a
+     * missing capability, authentication, schema, transport, a server error --
+     * is raised.
+     */
+    private putIfAbsentThroughTransaction;
+    /**
+     * The runtime's atomic transaction, used as the version-fenced update surface.
+     *
+     * Returns the same shape a runtime's own `cas` returns. The authority owns
+     * the next version, so the proposed value carries none.
+     */
+    private updateIfVersionThroughTransaction;
     /**
      * Atomically insert a record only if the key does not already exist.
-     * Process-safe across independent Node.js processes.
+     *
+     * Process-safe on the file runtime and across clients against an authority:
+     * the condition is evaluated by the runtime inside its own commit boundary,
+     * never by this method. A runtime without a dedicated conditional create
+     * uses its atomic transaction, so this means the same thing everywhere.
+     *
+     * The created record starts at `__version: 1`, so it can be fenced by
+     * `updateIfVersion` immediately.
      *
      * @returns {inserted: true, value: newRecord} if this call created the record
      * @returns {inserted: false, value: existingRecord} if record already existed

package/dist/collection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAIL,KAAK,mBAAmB,EACxB,KAAK,QAAQ,EACd,MAAM,gBAAgB,CAAC;AAIxB,OAAO,KAAK,EAAE,WAAW,EAAc,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAErF,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC;AAChD,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,gGAAgG;IAChG,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC;IACnC,4EAA4E;IAC5E,eAAe,EAAE,OAAO,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,iEAAiE;IACjE,IAAI,CAAC,EAAE,CAAC,GAAG;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACjC,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,qBAAa,UAAU,CAAC,CAAC;IACvB,OAAO,CAAC,EAAE,CAAO;IACjB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,oBAAoB,CAA8B;IAC1D,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,kBAAkB,CAA6B;IACvD,OAAO,CAAC,YAAY,CAAoC;IACxD,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,aAAa,CAAS;IAC9B,mFAAmF;IACnF,OAAO,CAAC,eAAe,CAAK;IAC5B,gFAAgF;IAChF,OAAO,CAAC,iBAAiB,CAAM;IAC/B,OAAO,CAAC,QAAQ,CAAoC;IACpD,oEAAoE;IACpE,OAAO,CAAC,WAAW,CAA+B;IAClD,kFAAkF;IAClF,OAAO,CAAC,eAAe,CAAuB;IAC9C;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc,CAAyB;IAC/C,yEAAyE;IACzE,OAAO,CAAC,aAAa,CAA+B;gBAExC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,WAAW,UAAO;IAoBxG;;OAEG;YACW,oBAAoB;IAalC;;;OAGG;IACG,GAAG,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC;IAKzB;;;;;;;;;;;;;OAaG;IACG,IAAI,CAAC,KAAK,GAAE,OAAO,CAAC,CAAC,CAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAsChD;;;;;OAKG;IACH,aAAa,IAAI,mBAAmB,GAAG,IAAI;IAI3C,wEAAwE;IACxE,OAAO,CAAC,QAAQ;IAWhB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAiBvB;;;;;;OAMG;IACH,OAAO,CAAC,wBAAwB;IA0BhC;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAWtC;;OAEG;IACH,WAAW,IAAI,WAAW,EAAE;IAI5B;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAYrC;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAazC;;OAEG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAYjD;;;OAGG;IACH,KAAK,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;IAO7C;;;OAGG;IACG,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA4BrE;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,eAAe,CACnB,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,aAAa,CAAC,EAAE,MAAM,EACtB,eAAe,CAAC,EAAE,MAAM,EACxB,gBAAgB,CAAC,EAAE,OAAO,EAC1B,YAAY,CAAC,EAAE,CAAC,GACf,OAAO,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;IAmEpC;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BhD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAK9B;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKnD;;;;;;OAMG;IACG,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,CAAC,CAAA;KAAE,CAAC;IAmClG;;;OAGG;IACH,SAAS,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,IAAI;IA6CxE,mEAAmE;IACnE,KAAK,IAAI,IAAI;IASb;;;;;;;;;;;OAWG;IACH,SAAS,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAIzC;;;;;;OAMG;IACH,kBAAkB,IAAI,cAAc,GAAG,IAAI;IAI3C;;;;;;;;;OASG;YACW,eAAe;IAQ7B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CA2E/B;AAED;;GAEG;AACH,qBAAa,YAAY,CAAC,MAAM,EAAE,KAAK;IACrC,OAAO,CAAC,QAAQ,CAAO;IACvB,OAAO,CAAC,OAAO,CAAO;IACtB,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,UAAU,CAAoC;gBAGpD,QAAQ,EAAE,IAAI,EACd,OAAO,EAAE,IAAI,EACb,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,GAAG,MAAM;IAQ/C;;OAEG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;CAoBxD"}
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAIL,KAAK,mBAAmB,EACxB,KAAK,QAAQ,EACd,MAAM,gBAAgB,CAAC;AAKxB,OAAO,KAAK,EAAE,WAAW,EAAc,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAErF,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC;AAChD,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC;AAiBjD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,gGAAgG;IAChG,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC;IACnC,4EAA4E;IAC5E,eAAe,EAAE,OAAO,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,iEAAiE;IACjE,IAAI,CAAC,EAAE,CAAC,GAAG;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACjC,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,qBAAa,UAAU,CAAC,CAAC;IACvB,OAAO,CAAC,EAAE,CAAO;IACjB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,oBAAoB,CAA8B;IAC1D,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,kBAAkB,CAA6B;IACvD,OAAO,CAAC,YAAY,CAAoC;IACxD,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,aAAa,CAAS;IAC9B,mFAAmF;IACnF,OAAO,CAAC,eAAe,CAAK;IAC5B,gFAAgF;IAChF,OAAO,CAAC,iBAAiB,CAAM;IAC/B,OAAO,CAAC,QAAQ,CAAoC;IACpD,oEAAoE;IACpE,OAAO,CAAC,WAAW,CAA+B;IAClD,kFAAkF;IAClF,OAAO,CAAC,eAAe,CAAuB;IAC9C;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc,CAAyB;IAC/C,yEAAyE;IACzE,OAAO,CAAC,aAAa,CAA+B;gBAExC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,WAAW,UAAO;IAoBxG;;OAEG;YACW,oBAAoB;IAalC;;;OAGG;IACG,GAAG,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC;IAKzB,qEAAqE;IAC/D,IAAI,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC;IAI1B;;;;;;;;;;;;;OAaG;IACG,IAAI,CAAC,KAAK,GAAE,OAAO,CAAC,CAAC,CAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAsChD,6EAA6E;IACvE,KAAK,CAAC,KAAK,GAAE,OAAO,CAAC,CAAC,CAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAIjD;;;;;OAKG;IACH,aAAa,IAAI,mBAAmB,GAAG,IAAI;IAI3C,wEAAwE;IACxE,OAAO,CAAC,QAAQ;IAWhB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAiBvB;;;;;;OAMG;IACH,OAAO,CAAC,wBAAwB;IA0BhC;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAWtC;;OAEG;IACH,WAAW,IAAI,WAAW,EAAE;IAI5B;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAYrC;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAazC;;OAEG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAYjD;;;OAGG;IACH,KAAK,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;IAO7C;;;OAGG;IACG,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA4BrE,qEAAqE;IAC/D,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIlE;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,eAAe,CACnB,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,aAAa,CAAC,EAAE,MAAM,EACtB,eAAe,CAAC,EAAE,MAAM,EACxB,gBAAgB,CAAC,EAAE,OAAO,EAC1B,YAAY,CAAC,EAAE,CAAC,GACf,OAAO,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;IA2EpC;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BhD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAK9B;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKnD;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;IAKjB;;;;;;;;OAQG;YACW,6BAA6B;IAkC3C;;;;;OAKG;YACW,iCAAiC;IAyE/C;;;;;;;;;;;;;OAaG;IACG,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,CAAC,CAAA;KAAE,CAAC;IAsClG;;;OAGG;IACH,SAAS,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,IAAI;IA6CxE,mEAAmE;IACnE,KAAK,IAAI,IAAI;IASb;;;;;;;;;;;OAWG;IACH,SAAS,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAIzC;;;;;;OAMG;IACH,kBAAkB,IAAI,cAAc,GAAG,IAAI;IAI3C;;;;;;;;;OASG;YACW,eAAe;IAQ7B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CA2E/B;AAED;;GAEG;AACH,qBAAa,YAAY,CAAC,MAAM,EAAE,KAAK;IACrC,OAAO,CAAC,QAAQ,CAAO;IACvB,OAAO,CAAC,OAAO,CAAO;IACtB,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,UAAU,CAAoC;gBAGpD,QAAQ,EAAE,IAAI,EACd,OAAO,EAAE,IAAI,EACb,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,GAAG,MAAM;IAQ/C;;OAEG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;CAoBxD"}

package/dist/collection.js

@@ -9,8 +9,23 @@
  */
 import { describeFreshness, isCacheCurrent, readRevision, } from './freshness.js';
 import { getReactiveDependencyGraph } from './reactive-graph.js';
+import { conditionalRefusal } from './transaction.js';
 import { IndexBackend } from './index-backend.js';
 import { IndexStore } from './index-store.js';
+/**
+ * A durable identity for one conditional write attempt.
+ *
+ * The authority deduplicates by transaction id, so a redelivered request
+ * cannot apply the same conditional write twice. Each *attempt* gets its own
+ * id: a retry after a conflict is a new decision against fresh state and has
+ * to be evaluated again rather than answered from the first attempt.
+ */
+function conditionalTransactionId(purpose) {
+    const unique = typeof globalThis.crypto?.randomUUID === 'function'
+        ? globalThis.crypto.randomUUID()
+        : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+    return `${purpose}-${unique}`;
+}
 /**
  * A live collection that automatically updates when underlying data changes.
  * Represents application state, not a one-time query result.
@@ -96,6 +111,10 @@ export class Collection {
         await this.refresh();
         return [...this.cache];
     }
+    /** List records through the canonical application collection API. */
+    async list() {
+        return this.all();
+    }
     /**
      * Find records whose fields match the supplied query.
      *
@@ -142,6 +161,10 @@ export class Collection {
         };
         return found;
     }
+    /** Query records by field equality through the canonical application API. */
+    async query(query = {}) {
+        return this.find(query);
+    }
     /**
      * How the most recent `find` was answered.
      *
@@ -325,6 +348,10 @@ export class Collection {
         await graph.emitChange(this.name, change);
         return String(recordId);
     }
+    /** Put a record through the canonical application collection API. */
+    async put(data, id) {
+        return this.insert(data, id);
+    }
     /**
      * Update a record in this collection.
      */
@@ -361,6 +388,10 @@ export class Collection {
      * The version check and update happen atomically at the backend boundary,
      * ensuring exactly one writer succeeds when multiple writers race.
      *
+     * A runtime without a dedicated compare-and-set carries the same fence
+     * through its atomic transaction, so this means the same thing on the file
+     * runtime as it does against a managed authority.
+     *
      * @param id Record identifier
      * @param expectedVersion The version you observed when you read this record
      * @param updates Fields to update (does not include __version; version is auto-incremented)
@@ -394,21 +425,32 @@ export class Collection {
         delete cleanUpdates.__version;
         const updated = { ...current, ...cleanUpdates };
         const key = `${this.name}:${id}`;
-        // Use CAS for atomic version-checked update
-        if (!this.db.cas) {
-            throw new Error(`updateIfVersion is not supported by this FeltDB runtime. ` +
-                `Only FileJsDb (Node.js) and HTTP/Server backends support atomic version-checked updates.`);
-        }
-        // Delegate authoritative version and epoch check to the backend
-        // The backend will atomically verify both predicates
-        const casResult = await this.db.cas({
-            key,
-            expectedVersion,
-            expectedEpoch,
-            expectedLeaseId,
-            rejectIfDiverged,
-            value: JSON.stringify(updated),
-        });
+        // Delegate the authoritative version and epoch check to the runtime, which
+        // evaluates both predicates inside its own commit boundary.
+        //
+        // A runtime that offers no single-record CAS but does offer an atomic
+        // transaction is not a runtime without compare-and-set: the transaction
+        // carries the same fence to the same authority. Routing through it is what
+        // keeps this helper's meaning the same everywhere, instead of making it a
+        // file-runtime privilege. Nothing here emulates CAS with separate reads
+        // and writes, because that would reintroduce the race the fence exists to
+        // remove.
+        const casResult = this.db.cas
+            ? await this.db.cas({
+                key,
+                expectedVersion,
+                expectedEpoch,
+                expectedLeaseId,
+                rejectIfDiverged,
+                value: JSON.stringify(updated),
+            })
+            : await this.updateIfVersionThroughTransaction(key, {
+                expectedVersion,
+                expectedEpoch,
+                expectedLeaseId,
+                rejectIfDiverged,
+                value: updated,
+            });
         if (!casResult.updated) {
             // Another writer won the race
             return {
@@ -478,24 +520,152 @@ export class Collection {
         const item = await this.get(id);
         return item !== null;
     }
+    /**
+     * Split a storage key back into the collection and record it addresses.
+     *
+     * The transaction contract is expressed in collections and ids rather than
+     * in storage keys, so a helper that holds a key has to name the record the
+     * same way the authority does.
+     */
+    addressOf(key) {
+        const separator = key.indexOf(':');
+        return { collection: key.slice(0, separator), id: key.slice(separator + 1) };
+    }
+    /**
+     * The runtime's atomic transaction, used as the conditional-create surface.
+     *
+     * Returns the same shape a runtime's own `putIfAbsent` returns, so the caller
+     * above cannot tell which route it took. A refusal that is a lost race is
+     * resolved by reading the record the winner wrote; anything else -- a
+     * missing capability, authentication, schema, transport, a server error --
+     * is raised.
+     */
+    async putIfAbsentThroughTransaction(key, value) {
+        const commit = this.db.commit_transaction;
+        if (!commit) {
+            throw new Error('putIfAbsent is not supported by this FeltDB runtime. It provides neither durable '
+                + 'atomic conditional creation nor an atomic transaction to carry the condition, and '
+                + 'FeltDB will not emulate one with a read followed by a write.');
+        }
+        const { collection, id } = this.addressOf(key);
+        try {
+            await commit.call(this.db, {
+                transactionId: conditionalTransactionId('put-if-absent'),
+                operations: [{ collection, id, value, requireAbsent: true }],
+            });
+        }
+        catch (error) {
+            if (!conditionalRefusal(error).conflict)
+                throw error;
+            const existing = await this.db.get(key);
+            if (!existing.success) {
+                throw new Error(existing.error || `could not read the record that won ${key}`);
+            }
+            if (!existing.data) {
+                throw new Error(`${key} was created and then removed while resolving a conditional create`);
+            }
+            return { inserted: false, value: existing.data };
+        }
+        // The authority assigns version 1 to a conditional create inside the
+        // commit boundary, which is the version this call already supplied.
+        return { inserted: true, value: JSON.stringify({ ...value, __version: 1 }) };
+    }
+    /**
+     * The runtime's atomic transaction, used as the version-fenced update surface.
+     *
+     * Returns the same shape a runtime's own `cas` returns. The authority owns
+     * the next version, so the proposed value carries none.
+     */
+    async updateIfVersionThroughTransaction(key, fence) {
+        const commit = this.db.commit_transaction;
+        if (!commit) {
+            throw new Error('updateIfVersion is not supported by this FeltDB runtime. It provides neither atomic '
+                + 'version-checked update nor an atomic transaction to carry the condition, and FeltDB '
+                + 'will not emulate one with a read followed by a write.');
+        }
+        if (fence.rejectIfDiverged) {
+            throw new Error('rejectIfDiverged is a replication predicate this runtime\'s transaction contract cannot '
+                + 'express, so it is refused rather than silently dropped.');
+        }
+        const { collection, id } = this.addressOf(key);
+        const proposed = { ...fence.value };
+        delete proposed.__version;
+        try {
+            await commit.call(this.db, {
+                transactionId: conditionalTransactionId('update-if-version'),
+                operations: [{
+                        collection, id, value: proposed,
+                        expectedVersion: fence.expectedVersion,
+                        expectedEpoch: fence.expectedEpoch,
+                        expectedLeaseId: fence.expectedLeaseId,
+                    }],
+            });
+        }
+        catch (error) {
+            const refusal = conditionalRefusal(error);
+            if (!refusal.conflict)
+                throw error;
+            const failure = refusal.failure;
+            const conflictCode = failure?.predicate === 'version' ? 'VERSION_CONFLICT'
+                : failure?.predicate === 'epoch' ? 'AUTHORITY_CONFLICT'
+                    : failure?.predicate === 'lease' ? 'LEASE_CONFLICT'
+                        : failure?.predicate === 'missing' ? 'RECORD_MISSING'
+                            : undefined;
+            if (failure?.predicate === 'version' && typeof failure.actual === 'number') {
+                return { updated: false, currentVersion: failure.actual, conflictCode };
+            }
+            // The refusal did not name a version, so the authority is asked for the
+            // one it holds -- which is what the caller would have to do next anyway.
+            const current = await this.db.get(key);
+            const record = current.success && current.data
+                ? JSON.parse(current.data)
+                : undefined;
+            return {
+                updated: false,
+                currentVersion: typeof record?.__version === 'number' ? record.__version : 0,
+                currentEpoch: record?.authority?.epoch,
+                conflictCode,
+            };
+        }
+        const nextVersion = fence.expectedVersion + 1;
+        return {
+            updated: true,
+            currentVersion: nextVersion,
+            currentEpoch: fence.expectedEpoch,
+            item: { ...proposed, id, __version: nextVersion },
+        };
+    }
     /**
      * Atomically insert a record only if the key does not already exist.
-     * Process-safe across independent Node.js processes.
+     *
+     * Process-safe on the file runtime and across clients against an authority:
+     * the condition is evaluated by the runtime inside its own commit boundary,
+     * never by this method. A runtime without a dedicated conditional create
+     * uses its atomic transaction, so this means the same thing everywhere.
+     *
+     * The created record starts at `__version: 1`, so it can be fenced by
+     * `updateIfVersion` immediately.
      *
      * @returns {inserted: true, value: newRecord} if this call created the record
      * @returns {inserted: false, value: existingRecord} if record already existed
      */
     async putIfAbsent(id, data) {
         const key = `${this.name}:${id}`;
+        // Version 1 is supplied here for the same reason `insert` supplies it: a
+        // record with no version could never be conditionally updated, which would
+        // make atomic creation useless for exactly the lifecycles that need it.
         const stored = typeof data === 'object' && data !== null
-            ? { ...data, id }
+            ? { ...data, id, __version: 1 }
             : data;
         const stringValue = JSON.stringify(stored);
-        if (!this.db.putIfAbsent) {
-            throw new Error(`putIfAbsent is not supported by this FeltDB runtime. ` +
-                `Only FileJsDb (Node.js) supports durable atomic conditional creation.`);
-        }
-        const result = await this.db.putIfAbsent(key, stringValue);
+        // A runtime that cannot create conditionally by itself but can commit an
+        // atomic transaction has the capability under a different name, and the
+        // transaction carries the same `requireAbsent` predicate to the same
+        // authority. See `updateIfVersion` for why this is a route and not an
+        // emulation.
+        const result = this.db.putIfAbsent
+            ? await this.db.putIfAbsent(key, stringValue)
+            : await this.putIfAbsentThroughTransaction(key, stored);
         // Emit change through reactive dependency graph if this was a new insert
         if (result.inserted) {
             const change = {

package/dist/create/create.js

@@ -79,8 +79,10 @@ export async function createProject(options) {
     }
     fs.writeFileSync(path.join(projectDir, 'package.json'), JSON.stringify(packageJson, null, 2));
     // Create feltdb.config.json
+    const deploymentMode = runtime === 'browser' ? 'browser' : runtime === 'node' ? 'local' : 'remote';
     const feltdbConfig = {
         namespace: applicationName,
+        mode: deploymentMode,
         runtime,
         storage: runtime === 'browser' ? 'indexeddb' : runtime === 'managed' ? 'managed' : 'durable',
         distributed,
@@ -195,13 +197,6 @@ ${hasAgents ? `  agent WorkspaceAssistant {
     }
     fs.writeFileSync(path.join(projectDir, 'tsconfig.json'), JSON.stringify(tsconfig, null, 2));
     // Create main application files
-    const runtimeOptions = runtime === 'browser'
-        ? "{ namespace: import.meta.env.VITE_FELTDB_NAMESPACE || '" + applicationName + "', browser: true }"
-        : runtime === 'managed'
-            ? "{ namespace: '" + applicationName + "', server: { url: import.meta.env.VITE_FELTDB_MANAGED_URL || '', applicationId: import.meta.env.VITE_FELTDB_MANAGED_APPLICATION_ID, environment: 'production' } }"
-            : runtime === 'self-hosted'
-                ? "{ namespace: import.meta.env.VITE_FELTDB_NAMESPACE || '" + applicationName + "', server: { url: import.meta.env.VITE_FELTDB_URL || 'http://localhost:7700', token: import.meta.env.VITE_FELTDB_API_KEY || '' } }"
-                : "{ namespace: import.meta.env.VITE_FELTDB_NAMESPACE || '" + applicationName + "', memory: true }";
     const feltdbTs = `import { configureDevelopmentRuntimeBridge, createFeltDB } from '@feltdb/core';
 
 configureDevelopmentRuntimeBridge({
@@ -214,7 +209,7 @@ configureDevelopmentRuntimeBridge({
   applicationUrl: import.meta.env.VITE_FELTDB_APPLICATION_URL,
 });
 
-export const db = createFeltDB(${runtimeOptions});
+export const db = createFeltDB();
 
 // Collections
 export const projects = db.collection('Project');
@@ -1198,7 +1193,7 @@ root.render(
             }
             fs.writeFileSync(path.join(projectDir, 'feltdb.flow'), fs.readFileSync(path.join(canonicalTemplate, 'feltdb.flow'), 'utf8').replace('app FeltDBStarter', `app ${appName}`));
             const databasePath = path.join(srcDir, 'feltdb.ts');
-            fs.writeFileSync(databasePath, fs.readFileSync(databasePath, 'utf8').replace(/export const managedRuntime[\s\S]*?\n\} : \{ namespace: import\.meta\.env\.VITE_FELTDB_NAMESPACE \|\| 'feltdb-starter', browser: true \}\);/, `export const managedRuntime = ${runtime === 'managed'};\nexport const db = createFeltDB(${runtimeOptions});`));
+            fs.writeFileSync(databasePath, fs.readFileSync(databasePath, 'utf8').replace(/export const managedRuntime[\s\S]*?\n\} : \{ namespace: import\.meta\.env\.VITE_FELTDB_NAMESPACE \|\| 'feltdb-starter', browser: true \}\);/, `export const managedRuntime = ${runtime === 'managed'};\nexport const db = createFeltDB();`));
         }
     }
     else {
@@ -1234,18 +1229,27 @@ main().catch(console.error);
     const envExample = `# FeltDB Configuration
 # Copy this file to .env.local and update the values
 
-# API key for authenticated self-hosted browser access
-VITE_FELTDB_API_KEY=
-
-# FeltDB Server URL (self-hosted or managed runtime)
-VITE_FELTDB_URL=http://localhost:7700
-
-# Managed example: https://runtime.your-app.feltdb.com
-VITE_FELTDB_MANAGED_URL=
-VITE_FELTDB_MANAGED_APPLICATION_ID=
-# Server/control-plane only. Never rename with a VITE_ prefix.
-FELTDB_MANAGED_CONTROL_API_KEY=
-FELTDB_TOKEN=
+  # Canonical application-plane deployment configuration consumed by createFeltDB()
+  # Supported public modes: browser, local, remote
+  VITE_FELTDB_MODE=${deploymentMode}
+  VITE_FELTDB_NAMESPACE=${applicationName}
+  VITE_FELTDB_ENVIRONMENT=development
+
+  # FeltDB Server URL (self-hosted or managed runtime)
+  VITE_FELTDB_URL=http://localhost:7700
+
+  # Optional credential for authenticated remote browser access
+  VITE_FELTDB_TOKEN=
+  # Legacy alias accepted by older tooling
+  VITE_FELTDB_API_KEY=
+
+  # Managed example: https://runtime.your-app.feltdb.com
+  VITE_FELTDB_MANAGED_URL=
+  VITE_FELTDB_MANAGED_APPLICATION_ID=
+  VITE_FELTDB_APPLICATION_ID=
+  # Server/control-plane only. Never rename with a VITE_ prefix.
+  FELTDB_MANAGED_CONTROL_API_KEY=
+  FELTDB_TOKEN=
 
 # Override the default self-hosted container image
 # By default the server image is built locally from the bundled source.

package/dist/create/managed-account.js

@@ -100,6 +100,17 @@ export async function configureManagedAccount(options) {
     }
     const environment = [
         '# Generated by create-feltdb managed setup. Do not commit this file.',
+        'FELTDB_MODE=remote',
+        `FELTDB_URL=${apiUrl}`,
+        `FELTDB_APPLICATION_ID=${application.id}`,
+        `FELTDB_NAMESPACE=${application.namespace || options.namespace}`,
+        'FELTDB_ENVIRONMENT=production',
+        '# Browser-safe deployment identity aliases.',
+        'VITE_FELTDB_MODE=remote',
+        `VITE_FELTDB_URL=${apiUrl}`,
+        `VITE_FELTDB_APPLICATION_ID=${application.id}`,
+        `VITE_FELTDB_NAMESPACE=${application.namespace || options.namespace}`,
+        'VITE_FELTDB_ENVIRONMENT=production',
         `VITE_FELTDB_MANAGED_URL=${apiUrl}`,
         `VITE_FELTDB_MANAGED_APPLICATION_ID=${application.id}`,
         '# Control-plane credential. Never prefix this with VITE_ or expose it to browser code.',

package/dist/create/package-versions.js

@@ -1,4 +1,4 @@
 // One release train keeps generated applications installable. The repository
 // validation script checks these values against every workspace manifest.
-export const FELTDB_PACKAGE_VERSION = '0.8.3';
+export const FELTDB_PACKAGE_VERSION = '0.8.4';
 export const feltdbPackageRange = `^${FELTDB_PACKAGE_VERSION}`;