@forge-cms/runtime 0.5.0 → 0.7.0

package/dist/errors.js

@@ -73,6 +73,67 @@ export class UniqueConstraintError extends ForgeError {
         this.fields = fields;
     }
 }
+/**
+ * A generic `create`/`update`/`delete` targeted a collection whose lifecycle the configured
+ * `AuthAdapter` owns (`AuthAdapter.managesCollection`, spec 061). Those mutations would bypass the
+ * adapter's invariants — first-admin provisioning, last-admin protection, password hashing, email
+ * normalisation, session versioning — so they are refused for every caller, trusted (`overrideAccess:
+ * true`) or not. Deliberately says nothing about which adapter or how; the way out is the auth
+ * adapter's own user-management operations.
+ */
+export class AuthManagedCollectionError extends ForgeError {
+    collection;
+    constructor(collection) {
+        super(`Collection '${collection}' is managed by the configured auth adapter and cannot be mutated ` +
+            `through generic collection CRUD. Use the auth adapter's user-management operations instead.`, 403, 'AUTH_MANAGED_COLLECTION');
+        this.collection = collection;
+    }
+}
+/**
+ * A versioned document mutation lost a race (spec 062): another write committed a new version of the
+ * same document after this one read it, so this one's document write and snapshot were rolled back
+ * together — nothing was written. Forge never retries it automatically (`before*` hooks may already
+ * have run); re-read the document and submit again. Deliberately names the public collection slug,
+ * never the internal `_versions_*` table whose unique index detected the conflict.
+ *
+ * Spec 064 reuses it for relation lifecycle conflicts — a referenced document deleted while a write was
+ * in progress, or a relation delete whose graph changed before it committed — with a `message` saying
+ * so. The meaning is the same: another request changed what this one depended on; nothing was written.
+ */
+export class ConcurrentModificationError extends ForgeError {
+    collection;
+    id;
+    constructor(collection, id, message) {
+        super(message ??
+            `Document '${id}' in '${collection}' was changed by another request while this one was in ` +
+                `progress; nothing was written. Reload it and try again.`, 409, 'CONCURRENT_MODIFICATION');
+        this.collection = collection;
+        this.id = id;
+    }
+}
+/**
+ * A request body over a Forge-owned size bound (spec 069; today: the auth JSON bodies read by
+ * `readBoundedJsonObject`). Says nothing about the body's contents.
+ */
+export class PayloadTooLargeError extends ForgeError {
+    constructor(message = 'Request body is too large') {
+        super(message, 413, 'PAYLOAD_TOO_LARGE');
+    }
+}
+/**
+ * The host's auth throttle refused a login/signup attempt (spec 069). The message is fixed and generic:
+ * it never says whether the account exists, which limit fired or how many attempts remain.
+ * `retryAfterSeconds` is already validated (a positive integer) when present; the auth handlers emit it
+ * as `Retry-After`.
+ */
+export class RateLimitedError extends ForgeError {
+    retryAfterSeconds;
+    constructor(retryAfterSeconds) {
+        super('Too many authentication attempts', 429, 'RATE_LIMITED');
+        if (retryAfterSeconds !== undefined)
+            this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
 export function isForgeError(err) {
     return err instanceof ForgeError;
 }

package/dist/errors.js.map

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

package/dist/files.d.ts

@@ -2,7 +2,11 @@ import type { ApiContext } from '@forge-cms/api';
 import type { AnyForgeCmsRuntime } from './runtime.js';
 export interface FileHandlerOptions<TEnv = unknown> {
     runtime: AnyForgeCmsRuntime<TEnv>;
-    /** `cache-control` for a hit. Defaults to a conservative minute. */
+    /**
+     * `cache-control` for a hit served to an **anonymous** caller. Defaults to a conservative minute. A
+     * hit for an authenticated caller is always `private, no-store` (spec 067): shared caches must not
+     * hand a file one user may read to another who may not.
+     */
     cacheControl?: string;
 }
 /**
@@ -19,6 +23,16 @@ export interface FileHandlerOptions<TEnv = unknown> {
  *   handleFile({ request: toWebRequest(event), params: { key: getRouterParam(event, 'key') ?? '' } }, { runtime })
  * );
  * ```
+ *
+ * **Access (spec 067).** A file is served only as part of the upload document that owns it: the document
+ * of the key's collection whose Forge-recorded `_storageKey` is this key. That document must be readable
+ * by the caller through the normal read pipeline (collection and row access, draft visibility), exactly
+ * as the Local API `findByID` with `overrideAccess: false` allows. It applies the collection's own
+ * `access.read`, **not** route-level options such as `requireAuth`/`allowedRoles` — a collection
+ * whose reads are gated only at its route must declare `access.read` to gate its files too. A key no
+ * document owns, or one whose document the
+ * caller cannot read, is the same `404` — it confirms nothing. A public bucket or CDN URL is outside
+ * this handler and outside Forge's access control.
  */
 export declare function handleFile<TEnv = unknown>(context: ApiContext<TEnv>, options: FileHandlerOptions<TEnv>): Promise<Response>;
 //# sourceMappingURL=files.d.ts.map

package/dist/files.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,MAAM,WAAW,kBAAkB,CAAC,IAAI,GAAG,OAAO;IAChD,OAAO,EAAE,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAClC,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,UAAU,CAAC,IAAI,GAAG,OAAO,EAC7C,OAAO,EAAE,UAAU,CAAC,IAAI,CAAC,EACzB,OAAO,EAAE,kBAAkB,CAAC,IAAI,CAAC,GAChC,OAAO,CAAC,QAAQ,CAAC,CAkCnB"}
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAKvD,MAAM,WAAW,kBAAkB,CAAC,IAAI,GAAG,OAAO;IAChD,OAAO,EAAE,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAClC;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,UAAU,CAAC,IAAI,GAAG,OAAO,EAC7C,OAAO,EAAE,UAAU,CAAC,IAAI,CAAC,EACzB,OAAO,EAAE,kBAAkB,CAAC,IAAI,CAAC,GAChC,OAAO,CAAC,QAAQ,CAAC,CA8CnB"}

package/dist/files.js

@@ -1,3 +1,6 @@
+import { AccessDeniedError, NotFoundError } from './errors.js';
+import { resolveOptionalUser } from './handlers.js';
+import { findStorageOwner } from './storage-intents.js';
 /**
  * Serves a stored file back over HTTP.
  *
@@ -12,35 +15,73 @@
  *   handleFile({ request: toWebRequest(event), params: { key: getRouterParam(event, 'key') ?? '' } }, { runtime })
  * );
  * ```
+ *
+ * **Access (spec 067).** A file is served only as part of the upload document that owns it: the document
+ * of the key's collection whose Forge-recorded `_storageKey` is this key. That document must be readable
+ * by the caller through the normal read pipeline (collection and row access, draft visibility), exactly
+ * as the Local API `findByID` with `overrideAccess: false` allows. It applies the collection's own
+ * `access.read`, **not** route-level options such as `requireAuth`/`allowedRoles` — a collection
+ * whose reads are gated only at its route must declare `access.read` to gate its files too. A key no
+ * document owns, or one whose document the
+ * caller cannot read, is the same `404` — it confirms nothing. A public bucket or CDN URL is outside
+ * this handler and outside Forge's access control.
  */
 export async function handleFile(context, options) {
     const raw = context.params?.['key'];
-    if (!raw) {
-        return new Response(JSON.stringify({ error: 'Missing file key' }), {
-            status: 400,
-            headers: { 'content-type': 'application/json' }
-        });
+    if (!raw)
+        return json({ error: 'Missing file key' }, 400);
+    let key;
+    try {
+        key = decodeURIComponent(raw);
+    }
+    catch {
+        return json({ error: 'Malformed file key' }, 400);
     }
-    const key = decodeURIComponent(raw);
+    const { runtime } = options;
     try {
-        const object = await options.runtime.adapters.storage.get(key);
-        if (!object?.body) {
-            return new Response(JSON.stringify({ error: `File '${key}' not found` }), {
-                status: 404,
-                headers: { 'content-type': 'application/json' }
+        const owner = await findStorageOwner(runtime, key);
+        if (!owner)
+            return notFound(key);
+        const user = await resolveOptionalUser(context, runtime);
+        try {
+            await runtime.findByID({
+                collection: owner.collection,
+                id: owner.id,
+                user,
+                overrideAccess: false,
+                depth: 0
             });
         }
+        catch (err) {
+            if (err instanceof NotFoundError || err instanceof AccessDeniedError)
+                return notFound(key);
+            throw err;
+        }
+        const object = await runtime.adapters.storage.get(key);
+        if (!object?.body)
+            return notFound(key);
         return new Response(object.body, {
             status: 200,
             headers: {
                 'content-type': object.contentType ?? 'application/octet-stream',
-                'cache-control': options.cacheControl ?? 'public, max-age=60',
+                'cache-control': user === null ? (options.cacheControl ?? 'public, max-age=60') : 'private, no-store',
                 ...(object.size !== undefined && { 'content-length': String(object.size) })
             }
         });
     }
-    catch (err) {
-        return new Response(JSON.stringify({ error: err instanceof Error ? err.message : 'Failed to read file' }), { status: 500, headers: { 'content-type': 'application/json' } });
+    catch {
+        // No driver or storage message reaches the client (it can name buckets, tables or credentials).
+        return json({ error: 'Failed to read file' }, 500);
     }
 }
+function notFound(key) {
+    return json({ error: `File '${key}' not found` }, 404);
+}
+/** Error bodies are never cached: an anonymous `404` must not be served to the owner who may read it. */
+function json(body, status) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json', 'cache-control': 'no-store' }
+    });
+}
 //# sourceMappingURL=files.js.map

package/dist/files.js.map

@@ -1 +1 @@
-{"version":3,"file":"files.js","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,OAAyB,EACzB,OAAiC;IAEjC,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;IACpC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC,EAAE;YACjE,MAAM,EAAE,GAAG;YACX,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;SAChD,CAAC,CAAC;IACL,CAAC;IAED,MAAM,GAAG,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IAEpC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC/D,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC;YAClB,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,SAAS,GAAG,aAAa,EAAE,CAAC,EAAE;gBACxE,MAAM,EAAE,GAAG;gBACX,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;aAChD,CAAC,CAAC;QACL,CAAC;QAED,OAAO,IAAI,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE;YAC/B,MAAM,EAAE,GAAG;YACX,OAAO,EAAE;gBACP,cAAc,EAAE,MAAM,CAAC,WAAW,IAAI,0BAA0B;gBAChE,eAAe,EAAE,OAAO,CAAC,YAAY,IAAI,oBAAoB;gBAC7D,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,gBAAgB,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;aAC5E;SACF,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,IAAI,QAAQ,CACjB,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,qBAAqB,EAAE,CAAC,EACrF,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,EAAE,CACjE,CAAC;IACJ,CAAC;AACH,CAAC"}
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"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"}

package/dist/globals.d.ts

@@ -1,4 +1,4 @@
-import type { CmsUser } from '@forge-cms/core';
+import type { CmsUser, GlobalDefinition } from '@forge-cms/core';
 import type { DatabaseRecord } from '@forge-cms/db';
 import type { OperationContext } from './context.js';
 export interface GlobalBaseArgs {
@@ -8,17 +8,35 @@ export interface GlobalBaseArgs {
 }
 export interface GetGlobalArgs extends GlobalBaseArgs {
     depth?: 0 | 1;
+    /** Resolve `localized` fields to this locale (with fallback), for a global declaring `locales` (spec 066). */
+    locale?: string;
 }
 export interface UpdateGlobalArgs extends GlobalBaseArgs {
     data: Record<string, unknown>;
+    /** Write `localized` fields into this locale only, keeping the others (spec 066). Must be one of the global's `locales`. */
+    locale?: string;
 }
+/**
+ * The global options that exist on the shared collection types but can never apply to a singleton that
+ * is never created through `create` nor deleted (spec 066): delete hooks, and `create`/`delete` access
+ * rules. Refused at startup instead of being accepted and silently ignored. One message per problem.
+ * (Localized fields of globals are checked with collections', by `validateLocalizationSchema`.)
+ */
+export declare function validateGlobalSchema(globals: readonly GlobalDefinition[]): string[];
 /**
  * Reads the singleton global document. Returns `null` if the global has never been written.
  */
 export declare function getGlobal(ctx: OperationContext, args: GetGlobalArgs): Promise<DatabaseRecord | null>;
 /**
- * Creates or updates the singleton global document. Unlike collections, globals always have
- * exactly one document — the first write creates it, subsequent writes update it.
+ * Creates or updates the singleton global document. Unlike collections, globals always have exactly one
+ * document — the first write creates it, later writes update it.
+ *
+ * Later writes are **partial**, exactly like a collection `update()` (spec 066): omitted fields keep
+ * their stored values (defaults and the draft status apply to the first write only), validation runs on
+ * the merged document, and a `locale` write changes that locale of each `localized` field and keeps the
+ * others. A query-returning `access.update` rule must match the stored row, and cannot authorize the
+ * first write (there is no row to match). Two simultaneous first writes: one commits, the other gets
+ * `409 CONCURRENT_MODIFICATION` with nothing written.
  */
 export declare function updateGlobal(ctx: OperationContext, args: UpdateGlobalArgs): Promise<DatabaseRecord>;
 //# sourceMappingURL=globals.d.ts.map

package/dist/globals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"globals.d.ts","sourceRoot":"","sources":["../src/globals.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAoB,MAAM,iBAAiB,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AA0BrD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,aAAc,SAAQ,cAAc;IACnD,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;CACf;AAED,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AA6ED;;GAEG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAmDhC;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,cAAc,CAAC,CAsGzB"}
+{"version":3,"file":"globals.d.ts","sourceRoot":"","sources":["../src/globals.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAwB,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,KAAK,EAAwB,cAAc,EAAiB,MAAM,eAAe,CAAC;AAKzF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAuCrD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,aAAc,SAAQ,cAAc;IACnD,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IACd,8GAA8G;IAC9G,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,4HAA4H;IAC5H,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,EAAE,CAsBnF;AAiGD;;GAEG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CA+DhC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,cAAc,CAAC,CAyJzB"}

package/dist/globals.js

@@ -1,12 +1,55 @@
 import { validateCollection } from '@forge-cms/core';
-import { AccessDeniedError, ForgeError, InvalidInputError, NotFoundError, ValidationFailedError } from './errors.js';
+import { isAtomicWriteConditionError, isUniqueConstraintError as isDbUniqueConstraintError } from '@forge-cms/db';
+import { AccessDeniedError, ConcurrentModificationError, ForgeError, InvalidInputError, NotFoundError, ValidationFailedError } from './errors.js';
 import { documentMatches, resolveAccess } from './access.js';
-import { applyFieldDefaults } from './defaults.js';
+import { afterStamp } from './concurrency.js';
+import { applyAutoSlugs, applyFieldDefaults } from './defaults.js';
 import { statusConstraint } from './read-policy.js';
 import { populateRecord } from './populate.js';
 import { runAfterChangeHooks, runAfterOperationHooks, runAfterReadHooks, runBeforeChangeHooks, runBeforeOperationHooks, runBeforeValidateHooks, runFieldHooks } from './hooks.js';
 import { assertWritableFields, filterReadableFields, FieldAccessError } from './field-access.js';
+import { screenHookOutput, screenUpdateInput } from './system-fields.js';
+import { isLocalizedField, resolveLocalizedDocument, storeLocalizedDocument } from './localization.js';
+import { collectWrittenTargets, targetAssertions, verifyTargetsExist } from './relation-lifecycle.js';
 const GLOBAL_ID = 'global';
+/**
+ * The global options that exist on the shared collection types but can never apply to a singleton that
+ * is never created through `create` nor deleted (spec 066): delete hooks, and `create`/`delete` access
+ * rules. Refused at startup instead of being accepted and silently ignored. One message per problem.
+ * (Localized fields of globals are checked with collections', by `validateLocalizationSchema`.)
+ */
+export function validateGlobalSchema(globals) {
+    const errors = [];
+    for (const global of globals) {
+        const label = `Global '${global.slug}'`;
+        for (const hook of ['beforeDelete', 'afterDelete']) {
+            if ((global.hooks?.[hook]?.length ?? 0) > 0) {
+                errors.push(`${label} declares ${hook} hooks, but a global is never deleted, so they could never run (spec 066). Remove them.`);
+            }
+        }
+        for (const rule of ['create', 'delete']) {
+            if (global.access?.[rule] !== undefined) {
+                errors.push(`${label} declares access.${rule}, but a global only has read and update: its first write is ` +
+                    `an update and it is never deleted, so this rule could never apply (spec 066). Gate the ` +
+                    `first write with access.update.`);
+            }
+        }
+    }
+    return errors;
+}
+/** The collection-shaped view of a global the shared pipeline stages (hooks, validation, locales) take. */
+function proxyOf(global) {
+    return { ...global, upload: false };
+}
+function assertKnownLocale(global, locale) {
+    if (locale === undefined)
+        return;
+    if (!global.locales?.includes(locale)) {
+        throw new InvalidInputError(global.locales && global.locales.length > 0
+            ? `Unknown locale '${locale}' for global '${global.slug}'; expected one of ${global.locales.map((l) => `'${l}'`).join(', ')}`
+            : `Global '${global.slug}' is not localized; locale '${locale}' cannot be written`);
+    }
+}
 function getGlobalOrThrow(ctx, slug) {
     const global = ctx.getGlobal(slug);
     if (!global)
@@ -44,7 +87,7 @@ async function prepareGlobalForRead(ctx, global, record, args) {
         return null;
     const user = args.user ?? null;
     const overrideAccess = args.overrideAccess !== false;
-    const collectionProxy = { ...global, upload: false };
+    const collectionProxy = proxyOf(global);
     let doc = record;
     if (args.depth === 1) {
         doc = await populateRecord(doc, collectionProxy, ctx, {
@@ -55,6 +98,9 @@ async function prepareGlobalForRead(ctx, global, record, args) {
     if (args.overrideAccess === false) {
         doc = await filterReadableFields(doc, collectionProxy, user);
     }
+    if (args.locale !== undefined) {
+        doc = resolveLocalizedDocument(doc, collectionProxy, args.locale);
+    }
     const withFieldHooks = await runFieldHooks(collectionProxy, 'afterRead', {
         data: doc,
         operation: 'read',
@@ -71,8 +117,19 @@ export async function getGlobal(ctx, args) {
     const user = args.user ?? null;
     const overrideAccess = args.overrideAccess !== false;
     await runBeforeOperationHooks({ ...global, upload: false }, { operation: 'read', user, overrideAccess });
-    await checkGlobalAccess(global, 'read', args);
+    const decision = await checkGlobalAccess(global, 'read', args);
     const record = await ctx.adapters.database.findById(`_global_${global.slug}`, GLOBAL_ID);
+    // Spec 066: a query-returning read rule is a row-level grant, as on a collection read. A global row
+    // it does not match reads as `null` — the same answer as "never configured", confirming nothing.
+    if (record && decision.where && !documentMatches(record, decision.where)) {
+        await runAfterOperationHooks(proxyOf(global), {
+            operation: 'read',
+            user,
+            overrideAccess,
+            result: null
+        });
+        return null;
+    }
     // Draft visibility (spec 058 §8): a global was previously written but never gated its own
     // `_status` on read, so an anonymous caller could read a global's unpublished draft content the
     // exact same way an anonymous single-document read of a `drafts: true` collection cannot. Mirrors
@@ -94,23 +151,39 @@ export async function getGlobal(ctx, args) {
     return doc;
 }
 /**
- * Creates or updates the singleton global document. Unlike collections, globals always have
- * exactly one document — the first write creates it, subsequent writes update it.
+ * Creates or updates the singleton global document. Unlike collections, globals always have exactly one
+ * document — the first write creates it, later writes update it.
+ *
+ * Later writes are **partial**, exactly like a collection `update()` (spec 066): omitted fields keep
+ * their stored values (defaults and the draft status apply to the first write only), validation runs on
+ * the merged document, and a `locale` write changes that locale of each `localized` field and keeps the
+ * others. A query-returning `access.update` rule must match the stored row, and cannot authorize the
+ * first write (there is no row to match). Two simultaneous first writes: one commits, the other gets
+ * `409 CONCURRENT_MODIFICATION` with nothing written.
  */
 export async function updateGlobal(ctx, args) {
     const global = getGlobalOrThrow(ctx, args.global);
     const user = args.user ?? null;
     const overrideAccess = args.overrideAccess !== false;
-    const collectionProxy = { ...global, upload: false };
+    const collectionProxy = proxyOf(global);
+    assertKnownLocale(global, args.locale);
     await runBeforeOperationHooks(collectionProxy, { operation: 'update', user, overrideAccess });
     const existing = await ctx.adapters.database.findById(`_global_${global.slug}`, GLOBAL_ID);
-    await checkGlobalAccess(global, 'update', {
+    const operation = existing ? 'update' : 'create';
+    const decision = await checkGlobalAccess(global, 'update', {
         ...args,
         ...(existing !== null && { doc: existing })
     });
+    if (decision.where && !(existing && documentMatches(existing, decision.where))) {
+        throw new AccessDeniedError();
+    }
+    // Spec 063: a global row's `id`/timestamps/`_storageKey` belong to Forge. Echoes of the stored row
+    // are dropped; before the first write there is nothing to echo, so any of them is refused.
+    const stored = existing ?? {};
+    const input = screenUpdateInput(args.data, stored);
     if (args.overrideAccess === false) {
         try {
-            await assertWritableFields(args.data, collectionProxy, user, existing ? 'update' : 'create');
+            await assertWritableFields(input, collectionProxy, user, operation);
         }
         catch (err) {
             if (err instanceof FieldAccessError)
@@ -118,33 +191,61 @@ export async function updateGlobal(ctx, args) {
             throw err;
         }
     }
-    const seeded = applyFieldDefaults(collectionProxy, args.data);
+    // A locale write merges into the stored per-locale maps, so it is derived from `existing` and must
+    // commit only while the row is still the one it was merged from (compare-and-set below).
+    const localized = storeLocalizedDocument(input, collectionProxy, args.locale, existing ?? undefined);
+    const mergesLocales = existing !== null &&
+        args.locale !== undefined &&
+        Object.keys(input).some((name) => {
+            const field = global.fields[name];
+            return field !== undefined && isLocalizedField(field);
+        });
+    const seeded = existing
+        ? applyAutoSlugs(collectionProxy, localized, existing)
+        : applyAutoSlugs(collectionProxy, applyFieldDefaults(collectionProxy, localized));
     let data = await runRejectableStage(async () => runBeforeValidateHooks(collectionProxy, {
-        operation: existing ? 'update' : 'create',
+        operation,
         data: await runFieldHooks(collectionProxy, 'beforeValidate', {
             data: seeded,
-            operation: existing ? 'update' : 'create',
+            ...(existing !== null && { previousData: existing }),
+            operation,
             user,
             overrideAccess
         }),
+        ...(existing !== null && { previousData: existing }),
         user,
         overrideAccess
     }), 'beforeValidate hook');
-    if (global.drafts === true && data._status === undefined) {
+    data = screenHookOutput(data, stored, 'beforeValidate', `global '${global.slug}'`);
+    if (global.drafts === true && !existing && data._status === undefined) {
         data = { ...data, _status: 'draft' };
     }
     if (data._status !== undefined && data._status !== 'draft' && data._status !== 'published') {
         throw new InvalidInputError(`Invalid status '${String(data._status)}', expected 'draft' or 'published'`);
     }
-    const validation = validateCollection(collectionProxy, data);
-    if (!validation.valid)
-        throw new ValidationFailedError(validation.errors);
+    if (existing) {
+        // As a collection update: validate the merged document, report only what the caller can act on.
+        const validation = validateCollection(collectionProxy, { ...existing, ...data });
+        if (!validation.valid) {
+            const relevant = validation.errors.filter((e) => {
+                const top = e.field.split('.')[0] ?? e.field;
+                return data[top] !== undefined || existing[top] === undefined;
+            });
+            if (relevant.length > 0)
+                throw new ValidationFailedError(relevant);
+        }
+    }
+    else {
+        const validation = validateCollection(collectionProxy, data);
+        if (!validation.valid)
+            throw new ValidationFailedError(validation.errors);
+    }
     data = await runRejectableStage(async () => runBeforeChangeHooks(collectionProxy, {
-        operation: existing ? 'update' : 'create',
+        operation,
         data: await runFieldHooks(collectionProxy, 'beforeChange', {
             data,
             ...(existing !== null && { previousData: existing }),
-            operation: existing ? 'update' : 'create',
+            operation,
             user,
             overrideAccess
         }),
@@ -152,16 +253,22 @@ export async function updateGlobal(ctx, args) {
         user,
         overrideAccess
     }), 'beforeChange hook');
-    const globalCollection = `_global_${global.slug}`;
-    let record;
-    if (existing) {
-        record = await ctx.adapters.database.update(globalCollection, GLOBAL_ID, data);
-    }
-    else {
-        record = await ctx.adapters.database.create(globalCollection, { ...data, id: GLOBAL_ID });
-    }
+    data = screenHookOutput(data, stored, 'beforeChange', `global '${global.slug}'`);
+    // A global's relation/upload targets must exist, now and when it commits (spec 064 §4) — a global
+    // reference restricts deletion of its target, so it must never be written pointing at nothing.
+    const targets = collectWrittenTargets(global.fields, data, existing ?? undefined);
+    if (targets.size > 0)
+        await verifyTargetsExist(ctx, targets);
+    const record = await writeGlobal(ctx, {
+        global,
+        data,
+        existing,
+        compareAndSet: mergesLocales,
+        accessWhere: decision.where,
+        assertions: targets.size > 0 ? targetAssertions(targets) : []
+    });
     await runAfterChangeHooks(collectionProxy, {
-        operation: existing ? 'update' : 'create',
+        operation,
         data,
         ...(existing !== null && { previousData: existing }),
         result: record,
@@ -169,7 +276,9 @@ export async function updateGlobal(ctx, args) {
         user,
         overrideAccess
     });
-    const doc = await prepareGlobalForRead(ctx, global, record, args);
+    // Being allowed to write the global is not permission to read it back (spec 068).
+    const readable = args.overrideAccess !== false || (await canReadGlobal(global, record, user));
+    const doc = readable ? await prepareGlobalForRead(ctx, global, record, args) : { id: GLOBAL_ID };
     const result = doc ?? record;
     await runAfterOperationHooks(collectionProxy, {
         operation: 'update',
@@ -179,4 +288,83 @@ export async function updateGlobal(ctx, args) {
     });
     return result;
 }
+/** The read gate `getGlobal` applies, as a yes/no for the row just written. */
+async function canReadGlobal(global, record, user) {
+    let decision;
+    try {
+        decision = await checkGlobalAccess(global, 'read', { user, overrideAccess: false });
+    }
+    catch (err) {
+        if (err instanceof AccessDeniedError)
+            return false;
+        throw err;
+    }
+    if (decision.where && !documentMatches(record, decision.where))
+        return false;
+    const status = statusConstraint(proxyOf(global), undefined, user, false, 'all');
+    return !status || documentMatches(record, status);
+}
+/**
+ * Persists a prepared global write. The first write is a `create` of the fixed `global` row: of two
+ * simultaneous first writers, the row's primary key lets exactly one commit, and the other becomes a
+ * `409` instead of leaking the internal table's unique-constraint error (spec 066). A write carrying
+ * relation-target assertions (spec 064 §4), or a locale merge that must not overwrite a concurrent one
+ * (`compareAndSet`, on `updated_at`), is one `atomicWrite`; a failed condition is a `409`, nothing written.
+ */
+async function writeGlobal(ctx, input) {
+    const { global, data, existing, assertions } = input;
+    const table = `_global_${global.slug}`;
+    const database = ctx.adapters.database;
+    const concurrent = (message) => new ConcurrentModificationError(global.slug, GLOBAL_ID, message);
+    const conditions = [
+        ...(input.compareAndSet && existing ? [{ updated_at: existing.updated_at }] : []),
+        ...(input.accessWhere !== undefined ? [input.accessWhere] : [])
+    ];
+    const condition = conditions.length === 0
+        ? undefined
+        : conditions.length === 1
+            ? conditions[0]
+            : { and: conditions };
+    const write = !existing
+        ? { type: 'create', collection: table, data: { ...data, id: GLOBAL_ID } }
+        : condition !== undefined
+            ? {
+                type: 'updateIf',
+                collection: table,
+                id: GLOBAL_ID,
+                data,
+                condition: { targetMatches: condition },
+                requireApplied: true
+            }
+            : { type: 'update', collection: table, id: GLOBAL_ID, data };
+    if (input.compareAndSet && existing)
+        await afterStamp(existing.updated_at);
+    try {
+        if (assertions.length === 0 && write.type === 'create') {
+            return await database.create(table, write.data);
+        }
+        if (assertions.length === 0 && write.type === 'update') {
+            return await database.update(table, GLOBAL_ID, write.data);
+        }
+        const results = await database.atomicWrite([...assertions, write]);
+        const written = results[assertions.length];
+        if (written?.type === 'create' || written?.type === 'update')
+            return written.record;
+        if (written?.type === 'updateIf' && written.applied)
+            return written.record;
+        throw new Error('atomicWrite returned no global record');
+    }
+    catch (err) {
+        if (!existing && isDbUniqueConstraintError(err) && err.collection === table) {
+            throw concurrent(`Global '${global.slug}' was first written by another request at the same time; nothing was ` +
+                `written. Reload and try again.`);
+        }
+        if (isAtomicWriteConditionError(err)) {
+            throw concurrent(`Global '${global.slug}' was changed by another request while this write was in progress (another ` +
+                `locale was edited, it no longer matches the caller's update access, or a document it references ` +
+                `was deleted); nothing was written. Reload and try again.`);
+        }
+        throw err;
+    }
+}
 //# sourceMappingURL=globals.js.map