@haverstack/core 0.40.0 → 0.42.0

package/dist/stack/install-app.js

@@ -0,0 +1,260 @@
+/**
+ * App install verbs
+ * -------------------------------------------------------
+ * Planning, applying and withdrawing an app's install over an unscoped
+ * Stack: the bodies of Stack.planInstall(), installApp() and
+ * uninstallApp(), whose doc comments describe the contract. Written
+ * against Stack's public API alone, so every write here passes the same
+ * checks any other caller's would. See docs/spec/apps.md.
+ */
+import { ARGUMENTS_INVALID, StackConflictError, StackNotFoundError, StackSchemaDriftError, StackValidationError, } from '../errors.js';
+import { checkGrantValid } from '../grants.js';
+import { INSTALL_APP_LABEL, INSTALL_GRANT_LABEL, claimedFamilies, familyStanding, grantIsRequest, installAppLink, installGrantLink, installReader, linkedIds, namespaceOf, ownTypeIds, planFingerprint, sameRequest, snapshotManifest, } from '../install.js';
+import { baseIdOf, diffSchemas, hashSchema, parseTypeId } from '../schema.js';
+import { findAppCardByDid, loadInstallRecords, queryAllPages } from './reads.js';
+import { SYSTEM_TYPES } from '../types/index.js';
+import { validateSchemaFieldNames, validateSchemaReservedNames, validateSchemaShape, } from '../validate.js';
+export async function planInstall(stack, submitted, opts) {
+    const { did } = opts;
+    const manifest = snapshotManifest(submitted);
+    checkManifest(manifest, did);
+    const installs = await loadInstallRecords(stack);
+    const existing = installs.find((r) => r.content.appId === manifest.appId) ?? null;
+    const ownVersions = ownTypeIds(manifest);
+    const ownFamilies = new Set(ownVersions.map(baseIdOf));
+    const card = await findAppCardByDid(stack, did);
+    if (card && card.content.appId !== manifest.appId) {
+        throw new StackConflictError(`${did} is registered to "${card.content.appId}", not "${manifest.appId}"`);
+    }
+    const claimed = existing ? claimedFamilies(existing.content) : new Set();
+    const defined = new Set(existing?.content.defines ?? []);
+    const prior = existing?.content.requests ?? [];
+    const foreignRequests = [];
+    for (const r of manifest.requests) {
+        const standing = familyStanding(r.baseId, manifest.appId);
+        if (standing === 'own')
+            continue;
+        const owner = standing === 'foreign'
+            ? namespaceOf(r.baseId)
+            : standing === 'commons'
+                ? 'commons'
+                : 'system';
+        foreignRequests.push({ ...r, owner });
+    }
+    const typeChanges = [];
+    for (const t of manifest.types) {
+        const current = await stack.getType(t.id);
+        if (!current)
+            typeChanges.push({ id: t.id, change: 'new' });
+        else if (current.schemaHash !== (await hashSchema(t.schema))) {
+            // Refused here, not left to defineType(): installApp() defines types one
+            // by one, so a drift found there leaves the earlier ones written.
+            const violations = diffSchemas(current.schema, t.schema);
+            if (violations.length > 0)
+                throw new StackSchemaDriftError(t.id, violations);
+            typeChanges.push({ id: t.id, change: 'schema' });
+        }
+        else if (current.name !== t.name)
+            typeChanges.push({ id: t.id, change: 'name' });
+    }
+    const linkedKeys = [];
+    for (const id of existing ? linkedIds(existing, INSTALL_APP_LABEL) : []) {
+        const key = (await stack.get(id))?.content?.did;
+        if (typeof key === 'string')
+            linkedKeys.push(key);
+    }
+    return {
+        manifest,
+        did,
+        existing,
+        newFamilies: [...ownFamilies].filter((f) => !claimed.has(f)),
+        newVersions: ownVersions.filter((id) => !defined.has(id)),
+        requestsAdded: manifest.requests.filter((r) => !prior.some((p) => sameRequest(p, r))),
+        requestsRemoved: prior.filter((p) => !manifest.requests.some((r) => sameRequest(p, r))),
+        foreignRequests,
+        typeChanges,
+        newKey: !existing ||
+            !card ||
+            card.deletedAt !== undefined ||
+            !linkedIds(existing, INSTALL_APP_LABEL).includes(card.id),
+        linkedKeys,
+    };
+}
+export async function installApp(stack, plan) {
+    const fresh = await planInstall(stack, plan.manifest, { did: plan.did });
+    if (planFingerprint(fresh) !== planFingerprint(plan)) {
+        throw new StackConflictError(`The stack changed since the install of "${plan.manifest.appId}" was planned; plan it again`);
+    }
+    const { manifest, did, existing } = fresh;
+    for (const type of manifest.types)
+        await stack.defineType(type);
+    const card = await ensureAppCard(stack, manifest, did);
+    const defines = [...new Set([...(existing?.content.defines ?? []), ...ownTypeIds(manifest)])];
+    const requests = manifest.requests.map((r) => ({
+        baseId: r.baseId,
+        actions: [...r.actions],
+    }));
+    let install;
+    if (!existing) {
+        install = await stack.create(`${SYSTEM_TYPES.INSTALL}@1`, {
+            appId: manifest.appId,
+            name: manifest.name,
+            ...(manifest.version !== undefined && { version: manifest.version }),
+            defines,
+            requests,
+        }, { associations: [installAppLink(card.id)] });
+    }
+    else {
+        const current = existing.deletedAt ? await stack.undelete(existing.id) : existing;
+        install = await stack.patchContent(existing.id, { name: manifest.name, version: manifest.version ?? null, defines, requests }, { ifVersion: current.version });
+        if (!linkedIds(install, INSTALL_APP_LABEL).includes(card.id)) {
+            install = await stack.associate(install.id, [installAppLink(card.id)]);
+        }
+    }
+    return (await reconcileInstallGrants(stack, install));
+}
+export async function uninstallApp(stack, appId) {
+    const install = (await loadInstallRecords(stack)).find((r) => r.content.appId === appId && !r.deletedAt);
+    if (!install)
+        throw new StackNotFoundError(`No install for "${appId}"`);
+    const edits = [];
+    for (const id of linkedIds(install, INSTALL_GRANT_LABEL)) {
+        if (await stack.get(id))
+            await stack.delete(id);
+        edits.push({ op: 'remove', association: installGrantLink(id) });
+    }
+    if (edits.length > 0)
+        await stack.amendAssociations(install.id, edits);
+    const { record } = await stack.deleteAndReturn(install.id);
+    return record;
+}
+/** A manifest's own shape, and every request held to grantType()'s rules. */
+function checkManifest(manifest, did) {
+    const errors = [];
+    if (typeof did !== 'string' || !did.startsWith('did:')) {
+        errors.push({ path: 'did', message: 'Expected a DID' });
+    }
+    if (typeof manifest.appId !== 'string' || manifest.appId === '') {
+        errors.push({ path: 'appId', message: 'Expected a non-empty appId' });
+    }
+    if (typeof manifest.name !== 'string' || manifest.name === '') {
+        errors.push({ path: 'name', message: 'Expected a non-empty name' });
+    }
+    const seen = new Set();
+    manifest.types.forEach((t, i) => {
+        if (seen.has(t.id)) {
+            errors.push({ path: `types[${i}].id`, message: `"${t.id}" is listed more than once` });
+        }
+        seen.add(t.id);
+        const schemaPath = `types[${i}].schema`;
+        const shapeErrors = validateSchemaShape(t.schema, schemaPath);
+        errors.push(...shapeErrors);
+        if (shapeErrors.length === 0) {
+            const schema = t.schema;
+            for (const e of validateSchemaReservedNames(schema)) {
+                errors.push({ ...e, path: `${schemaPath}.${e.path}` });
+            }
+            validateSchemaFieldNames(schema, schemaPath, errors);
+        }
+        const parsed = parseTypeId(t.id);
+        if (!parsed) {
+            errors.push({ path: `types[${i}].id`, message: 'Expected a versioned TypeId' });
+        }
+        else {
+            const standing = familyStanding(parsed.baseId, manifest.appId);
+            if (standing === 'system' || standing === 'foreign') {
+                errors.push({
+                    path: `types[${i}].id`,
+                    message: standing === 'system'
+                        ? `"${parsed.baseId}" is a system type; no app can define it`
+                        : `"${parsed.baseId}" is outside the namespace "${manifest.appId}"; request access to it instead of defining it`,
+                });
+            }
+        }
+    });
+    if (errors.length > 0)
+        throw new StackValidationError(errors, ARGUMENTS_INVALID);
+    for (const r of manifest.requests)
+        checkGrantValid(r.baseId, r.actions);
+}
+/** The key's `_app` card, created or undeleted as needed. */
+async function ensureAppCard(stack, manifest, did) {
+    const card = await findAppCardByDid(stack, did);
+    if (!card) {
+        return stack.create(`${SYSTEM_TYPES.APP}@1`, {
+            appId: manifest.appId,
+            name: manifest.name,
+            ...(manifest.version !== undefined && { version: manifest.version }),
+            did,
+        });
+    }
+    return card.deletedAt ? stack.undelete(card.id) : card;
+}
+/**
+ * Make the grants linked to `install` exactly its `requests`, once per
+ * live linked key: withdraw any that no longer match, write any missing,
+ * and drop links to grants that are gone.
+ */
+async function reconcileInstallGrants(stack, install) {
+    const { requests } = install.content;
+    const dids = [];
+    for (const id of linkedIds(install, INSTALL_APP_LABEL)) {
+        const did = (await stack.get(id))?.content?.did;
+        if (typeof did === 'string')
+            dids.push(did);
+    }
+    const edits = [];
+    const held = [];
+    for (const id of linkedIds(install, INSTALL_GRANT_LABEL)) {
+        const grant = await stack.get(id);
+        const content = grant?.content;
+        const wanted = content !== undefined &&
+            baseIdOf(grant.typeId) === SYSTEM_TYPES.GRANT &&
+            dids.some((did) => requests.some((r) => grantIsRequest(content, r, did)));
+        if (wanted) {
+            held.push(content);
+            continue;
+        }
+        if (grant)
+            await stack.delete(id);
+        edits.push({ op: 'remove', association: installGrantLink(id) });
+    }
+    for (const did of dids) {
+        for (const r of requests) {
+            if (held.some((g) => grantIsRequest(g, r, did)))
+                continue;
+            const grant = await stack.grantType(r.baseId, {
+                actions: r.actions,
+                grantee: { kind: 'entity', entityId: did },
+            });
+            held.push(grant.content);
+            edits.push({ op: 'add', association: installGrantLink(grant.id) });
+        }
+    }
+    let result = edits.length > 0 ? await stack.amendAssociations(install.id, edits) : install;
+    // Each linked key may read its own install, which is how an app learns
+    // what was approved; a key of this app no longer linked may not.
+    // See docs/spec/apps.md § Over the wire.
+    const appKeys = new Set((await queryAllPages((q) => stack.query(q), {
+        filter: { baseId: SYSTEM_TYPES.APP, includeDeleted: true, includeUnlisted: true },
+    }))
+        .map((r) => r.content)
+        .filter((c) => c.appId === install.content.appId)
+        .map((c) => c.did));
+    const readerOf = (p) => p.kind === 'permission' && p.label === 'read' && p.grantee.kind === 'entity'
+        ? p.grantee.entityId
+        : null;
+    const current = (result.permissions ?? []).map(readerOf);
+    const access = [
+        ...dids
+            .filter((did) => !current.includes(did))
+            .map((entityId) => ({ op: 'add', association: installReader(entityId) })),
+        ...current
+            .filter((did) => did !== null && appKeys.has(did) && !dids.includes(did))
+            .map((entityId) => ({ op: 'remove', association: installReader(entityId) })),
+    ];
+    if (access.length > 0)
+        result = await stack.amendAccess(install.id, access);
+    return result;
+}
+//# sourceMappingURL=install-app.js.map

package/dist/stack/install-app.js.map

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

package/dist/stack/integrity.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Write invariants
+ * -------------------------------------------------------
+ * The integrity rules a Stack write owes whoever makes it — DID and appId
+ * bindings, containment, attachment metadata, `_config` ownership and a
+ * group's admin roster. They bind every requester, the stack owner
+ * included, which is why they live beneath `ScopedStack`'s permission
+ * gates rather than among them. Each reads unscoped: through the Stack it
+ * is handed, or a by-id `read` straight from its adapter.
+ */
+import type { RecordResolver } from '../access.js';
+import type { Association, AttachmentContent, DataAssociation, EntityId, RecordId, StackRecord, TypeId } from '../types/index.js';
+import type { Stack } from './stack.js';
+/** Uniqueness for every unique binding field a newly created card claims. */
+export declare function checkBindingsOnCreate(stack: Stack, typeId: TypeId, content: Record<string, unknown>): Promise<void>;
+/**
+ * Immutability for every binding field a patch touches, then uniqueness
+ * for the subset that carries it. Fields absent from the patch carry no
+ * new claim — a content patch is a merge, so an untouched binding is the one the
+ * card already holds.
+ */
+export declare function checkBindingsOnUpdate(stack: Stack, typeId: TypeId, id: RecordId, patch: Record<string, unknown | null>, existing: Record<string, unknown>, merged: Record<string, unknown>): Promise<void>;
+/**
+ * Bindings across a migration, whose content replaces the old wholesale.
+ * Immutability is asked over both families' binding fields, so a card can
+ * neither shed a DID by migrating out nor pick one up on the way in;
+ * uniqueness, of the destination only. See docs/spec/identity.md § DID bindings.
+ */
+export declare function checkBindingsOnMigrate(stack: Stack, fromTypeId: TypeId, toTypeId: TypeId, id: RecordId, existing: Record<string, unknown>, content: Record<string, unknown>): Promise<void>;
+/**
+ * A binding is permanent once made: uniqueness stops a second card claiming
+ * a value, but only immutability stops an existing card being moved onto
+ * one. A subject whose key changes gets a new card.
+ * See docs/spec/identity.md § DID bindings.
+ */
+export declare function checkBindingImmutable(family: string, field: 'did' | 'appId', existing: unknown, next: unknown): void;
+/**
+ * A caller-named `parentId` is a well-formed id of a record that exists —
+ * format first, so a malformed one is a 400 naming the problem. A restore
+ * names no destination and does not ask this.
+ * See docs/spec/data-model.md § Reparenting.
+ */
+export declare function assertParentExists(read: RecordResolver, id: string, parentId: string): Promise<void>;
+/**
+ * Refuse an edge that would make a record its own ancestor. Walks with an
+ * unscoped `read`, since links a requester cannot read could otherwise
+ * close a cycle. Read-then-write, so racing moves can both pass.
+ * See docs/spec/data-model.md § Reparenting.
+ */
+export declare function assertNoParentCycle(read: RecordResolver, id: string, parentId: string): Promise<void>;
+/**
+ * The `_attachment@1` fields a write may not move, each with the message it
+ * is refused by. Ordered as reported. See docs/spec/attachments.md § The
+ * `_attachment` record type.
+ */
+declare const ATTACHMENT_IMMUTABLE_FIELDS: readonly [readonly ["mimeType", "mimeType is immutable after creation; delete and re-upload to change it"], readonly ["fileId", "fileId is immutable"], readonly ["size", "size is immutable"]];
+type AttachmentImmutableField = (typeof ATTACHMENT_IMMUTABLE_FIELDS)[number][0];
+/**
+ * mimeType belongs to the fileId: its first metadata record fixes it, and
+ * a conflicting later one is refused. Best-effort against a racing first
+ * upload; what survives the race is a deterministic winner. See
+ * docs/spec/attachments.md § The `_attachment` record type.
+ */
+export declare function checkAttachmentMimeTypeOnCreate(stack: Stack, content: AttachmentContent): Promise<void>;
+/**
+ * An `attachmentRecordId` must name an `_attachment` record for the same
+ * `fileId`. Pointers already in `stored` are not re-asked, so restating an
+ * association never fails for a record deleted since.
+ * See docs/spec/attachments.md § Naming the upload a reference came from.
+ */
+export declare function checkAttachmentAssociationPointers(read: RecordResolver, associations: Association[] | undefined, stored?: Association[]): Promise<void>;
+/**
+ * Refuse a write that moves an `_attachment@1` record's fileId, size or
+ * mimeType. `violates` decides what counts as a move, since a patch names
+ * only what it changes while a migration re-sends all three.
+ * See docs/spec/attachments.md § The `_attachment` record type.
+ */
+export declare function assertAttachmentImmutable(violates: (field: AttachmentImmutableField) => boolean): void;
+/**
+ * `_config.entityId` defines stack ownership; neither patchContent() nor
+ * restoreVersion() may change it. A conflict with stack integrity, not a
+ * schema violation — hence StackConflictError. See docs/spec.md § The
+ * `_config` record.
+ */
+export declare function checkConfigEntityIdUnchanged(existingEntityId: EntityId, newEntityId: EntityId): void;
+/**
+ * Refuse a write that would leave a `_group` Record with no `admin`, asked
+ * of the roster the write would produce. An integrity rule, not a
+ * permission, so it binds the stack owner too.
+ * See docs/spec/identity.md § Group.
+ */
+export declare function assertGroupAdminRemains(record: StackRecord, next: DataAssociation[]): void;
+export {};
+//# sourceMappingURL=integrity.d.ts.map

package/dist/stack/integrity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrity.d.ts","sourceRoot":"","sources":["../../src/stack/integrity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AASnD,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,MAAM,EACP,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAMxC,6EAA6E;AAC7E,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,IAAI,CAAC,CAKf;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,QAAQ,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC,EACrC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,KAAK,EACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,QAAQ,EACZ,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,IAAI,CAAC,CAgBf;AAkCD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK,GAAG,OAAO,EACtB,QAAQ,EAAE,OAAO,EACjB,IAAI,EAAE,OAAO,GACZ,IAAI,CASN;AAcD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,cAAc,EACpB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,cAAc,EACpB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAgBf;AAMD;;;;GAIG;AACH,QAAA,MAAM,2BAA2B,iMAIvB,CAAC;AAEX,KAAK,wBAAwB,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAEhF;;;;;GAKG;AACH,wBAAsB,+BAA+B,CACnD,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;;;;GAKG;AACH,wBAAsB,kCAAkC,CACtD,IAAI,EAAE,cAAc,EACpB,YAAY,EAAE,WAAW,EAAE,GAAG,SAAS,EACvC,MAAM,GAAE,WAAW,EAAO,GACzB,OAAO,CAAC,IAAI,CAAC,CAqCf;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,OAAO,GACrD,IAAI,CAON;AAMD;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,gBAAgB,EAAE,QAAQ,EAC1B,WAAW,EAAE,QAAQ,GACpB,IAAI,CAON;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe,EAAE,GAAG,IAAI,CAO1F"}

package/dist/stack/integrity.js

@@ -0,0 +1,268 @@
+/**
+ * Write invariants
+ * -------------------------------------------------------
+ * The integrity rules a Stack write owes whoever makes it — DID and appId
+ * bindings, containment, attachment metadata, `_config` ownership and a
+ * group's admin roster. They bind every requester, the stack owner
+ * included, which is why they live beneath `ScopedStack`'s permission
+ * gates rather than among them. Each reads unscoped: through the Stack it
+ * is handed, or a by-id `read` straight from its adapter.
+ */
+import { hasGroupAdmin, isGroupRecord } from '../access.js';
+import { ARGUMENTS_INVALID, StackConflictError, StackValidationError } from '../errors.js';
+import { bindingFieldsOf, uniqueBindingFieldsOf } from './identity-bindings.js';
+import { filtersContent } from '../query-validation.js';
+import { associationIdentical } from '../associations/identity.js';
+import { validateRecordId } from './record-id.js';
+import { baseIdOf } from '../schema.js';
+import { findFirstMatch } from './reads.js';
+import { SYSTEM_TYPES } from '../types/index.js';
+// -------------------------------------------------------
+// DID and appId bindings
+// -------------------------------------------------------
+/** Uniqueness for every unique binding field a newly created card claims. */
+export async function checkBindingsOnCreate(stack, typeId, content) {
+    const family = baseIdOf(typeId);
+    for (const field of uniqueBindingFieldsOf(family)) {
+        await checkBindingUnique(stack, family, field, content[field]);
+    }
+}
+/**
+ * Immutability for every binding field a patch touches, then uniqueness
+ * for the subset that carries it. Fields absent from the patch carry no
+ * new claim — a content patch is a merge, so an untouched binding is the one the
+ * card already holds.
+ */
+export async function checkBindingsOnUpdate(stack, typeId, id, patch, existing, merged) {
+    const family = baseIdOf(typeId);
+    const unique = uniqueBindingFieldsOf(family);
+    for (const field of bindingFieldsOf(family)) {
+        if (!(field in patch))
+            continue;
+        checkBindingImmutable(family, field, existing[field], merged[field]);
+        if (unique.includes(field)) {
+            await checkBindingUnique(stack, family, field, merged[field], id);
+        }
+    }
+}
+/**
+ * Bindings across a migration, whose content replaces the old wholesale.
+ * Immutability is asked over both families' binding fields, so a card can
+ * neither shed a DID by migrating out nor pick one up on the way in;
+ * uniqueness, of the destination only. See docs/spec/identity.md § DID bindings.
+ */
+export async function checkBindingsOnMigrate(stack, fromTypeId, toTypeId, id, existing, content) {
+    const fromFamily = baseIdOf(fromTypeId);
+    const toFamily = baseIdOf(toTypeId);
+    const checked = new Set();
+    for (const family of fromFamily === toFamily ? [fromFamily] : [fromFamily, toFamily]) {
+        for (const field of bindingFieldsOf(family)) {
+            if (checked.has(field))
+                continue;
+            checked.add(field);
+            checkBindingImmutable(family, field, existing[field], content[field]);
+        }
+    }
+    for (const field of uniqueBindingFieldsOf(toFamily)) {
+        await checkBindingUnique(stack, toFamily, field, content[field], id);
+    }
+}
+/**
+ * Refuse a second card claiming a value an Actor is resolved by. A
+ * property of the set rather than the value, so no schema can say it.
+ * Read-then-write: two racing creates can both pass.
+ * See docs/spec/identity.md § DID bindings.
+ */
+async function checkBindingUnique(stack, family, field, value, excludeId) {
+    if (typeof value !== 'string' || value === '')
+        return;
+    const clash = await findFirstMatch((q) => stack.query(q), {
+        filter: {
+            baseId: family,
+            includeDeleted: true,
+            includeUnlisted: true,
+            ...(filtersContent(stack.capabilities) && { content: { [field]: value } }),
+        },
+    }, (r) => r.id !== excludeId && r.content[field] === value);
+    if (clash) {
+        throw new StackConflictError(`Another ${family} record already claims the ${field} "${value}"`);
+    }
+}
+/**
+ * A binding is permanent once made: uniqueness stops a second card claiming
+ * a value, but only immutability stops an existing card being moved onto
+ * one. A subject whose key changes gets a new card.
+ * See docs/spec/identity.md § DID bindings.
+ */
+export function checkBindingImmutable(family, field, existing, next) {
+    if (typeof existing !== 'string' || existing === '')
+        return;
+    if (next === existing)
+        return;
+    throw new StackValidationError([
+        {
+            path: field,
+            message: `${field} is immutable once set; register a new ${family} record instead`,
+        },
+    ]);
+}
+// -------------------------------------------------------
+// Containment
+// -------------------------------------------------------
+/**
+ * How far a change set's `parentId` will walk a proposed ancestor chain before refusing
+ * the move. Bounds the reads one call can cost; a hierarchy deeper than
+ * this is beyond what `parentId` is for. See docs/spec/data-model.md
+ * § Reparenting.
+ */
+const MAX_PARENT_DEPTH = 64;
+/**
+ * A caller-named `parentId` is a well-formed id of a record that exists —
+ * format first, so a malformed one is a 400 naming the problem. A restore
+ * names no destination and does not ask this.
+ * See docs/spec/data-model.md § Reparenting.
+ */
+export async function assertParentExists(read, id, parentId) {
+    validateRecordId(parentId, 'parentId');
+    if (!(await read(parentId))) {
+        throw new StackConflictError(`Cannot parent record "${id}" to "${parentId}": no such record. A container has to ` +
+            'exist when it is named.');
+    }
+}
+/**
+ * Refuse an edge that would make a record its own ancestor. Walks with an
+ * unscoped `read`, since links a requester cannot read could otherwise
+ * close a cycle. Read-then-write, so racing moves can both pass.
+ * See docs/spec/data-model.md § Reparenting.
+ */
+export async function assertNoParentCycle(read, id, parentId) {
+    let cursor = parentId;
+    for (let depth = 0; cursor !== undefined; depth++) {
+        if (cursor === id) {
+            throw new StackConflictError(`Cannot parent record "${id}" to "${parentId}": it is a descendant of "${id}", ` +
+                'and the move would make the record its own ancestor.');
+        }
+        // The cap bounds work, and guarantees this terminates on a chain that
+        // is already cyclic. It does not refuse the move: a chain this long is
+        // past what the check can speak to, not evidence of a loop, and
+        // refusing it would claim an invariant core does not maintain.
+        if (depth >= MAX_PARENT_DEPTH)
+            return;
+        cursor = (await read(cursor))?.parentId;
+    }
+}
+// -------------------------------------------------------
+// Attachments
+// -------------------------------------------------------
+/**
+ * The `_attachment@1` fields a write may not move, each with the message it
+ * is refused by. Ordered as reported. See docs/spec/attachments.md § The
+ * `_attachment` record type.
+ */
+const ATTACHMENT_IMMUTABLE_FIELDS = [
+    ['mimeType', 'mimeType is immutable after creation; delete and re-upload to change it'],
+    ['fileId', 'fileId is immutable'],
+    ['size', 'size is immutable'],
+];
+/**
+ * mimeType belongs to the fileId: its first metadata record fixes it, and
+ * a conflicting later one is refused. Best-effort against a racing first
+ * upload; what survives the race is a deterministic winner. See
+ * docs/spec/attachments.md § The `_attachment` record type.
+ */
+export async function checkAttachmentMimeTypeOnCreate(stack, content) {
+    const { fileId, mimeType } = content;
+    if (typeof fileId !== 'string')
+        return; // schema validation already rejected this
+    const existing = await stack.getAttachmentRecords(fileId);
+    if (existing.length === 0)
+        return;
+    const establishedMimeType = existing[0].content.mimeType;
+    if (mimeType !== establishedMimeType) {
+        // Deliberately does not name the established mimeType — that would
+        // confirm a guessed fileId's content type. See the anti-oracle rule
+        // in docs/spec/attachments.md.
+        throw new StackValidationError([
+            {
+                path: 'mimeType',
+                message: 'mimeType conflicts with the mimeType already established for this fileId',
+            },
+        ]);
+    }
+}
+/**
+ * An `attachmentRecordId` must name an `_attachment` record for the same
+ * `fileId`. Pointers already in `stored` are not re-asked, so restating an
+ * association never fails for a record deleted since.
+ * See docs/spec/attachments.md § Naming the upload a reference came from.
+ */
+export async function checkAttachmentAssociationPointers(read, associations, stored = []) {
+    const pointed = (associations ?? []).flatMap((association) => association.kind === 'attachment' &&
+        association.attachmentRecordId !== undefined &&
+        !stored.some((a) => associationIdentical(a, association))
+        ? [{ fileId: association.fileId, attachmentRecordId: association.attachmentRecordId }]
+        : []);
+    // One round trip per pointer, taken together: a change set carries a
+    // whole association list, and each pointer is an independent read.
+    const named = await Promise.all(pointed.map(({ attachmentRecordId }) => read(attachmentRecordId)));
+    pointed.forEach(({ fileId }, i) => {
+        const record = named[i];
+        const content = record?.content;
+        if (record &&
+            baseIdOf(record.typeId) === SYSTEM_TYPES.ATTACHMENT &&
+            content?.fileId === fileId) {
+            return;
+        }
+        // One message for every way of failing, so this is no existence oracle
+        // for records the caller cannot read. See docs/spec/attachments.md
+        // § Creating `_attachment@1` records directly.
+        throw new StackValidationError([
+            {
+                path: 'attachmentRecordId',
+                message: 'attachmentRecordId must name an `_attachment` record for this fileId',
+            },
+        ], ARGUMENTS_INVALID);
+    });
+}
+/**
+ * Refuse a write that moves an `_attachment@1` record's fileId, size or
+ * mimeType. `violates` decides what counts as a move, since a patch names
+ * only what it changes while a migration re-sends all three.
+ * See docs/spec/attachments.md § The `_attachment` record type.
+ */
+export function assertAttachmentImmutable(violates) {
+    const errors = ATTACHMENT_IMMUTABLE_FIELDS.filter(([field]) => violates(field)).map(([path, message]) => ({ path, message }));
+    if (errors.length > 0) {
+        throw new StackValidationError(errors);
+    }
+}
+// -------------------------------------------------------
+// Stack identity and groups
+// -------------------------------------------------------
+/**
+ * `_config.entityId` defines stack ownership; neither patchContent() nor
+ * restoreVersion() may change it. A conflict with stack integrity, not a
+ * schema violation — hence StackConflictError. See docs/spec.md § The
+ * `_config` record.
+ */
+export function checkConfigEntityIdUnchanged(existingEntityId, newEntityId) {
+    if (newEntityId !== existingEntityId) {
+        throw new StackConflictError('Cannot change _config.entityId: it defines stack ownership. ' +
+            'Ownership transfer is not a supported operation.');
+    }
+}
+/**
+ * Refuse a write that would leave a `_group` Record with no `admin`, asked
+ * of the roster the write would produce. An integrity rule, not a
+ * permission, so it binds the stack owner too.
+ * See docs/spec/identity.md § Group.
+ */
+export function assertGroupAdminRemains(record, next) {
+    if (!isGroupRecord(record))
+        return;
+    if (hasGroupAdmin(next))
+        return;
+    throw new StackConflictError(`Cannot leave group "${record.id}" without an admin: a _group record's roster keeps at ` +
+        'least one `admin` relationship association. Name the incoming admin in the same write.');
+}
+//# sourceMappingURL=integrity.js.map