@gnolith/taproot 0.2.0 → 0.3.0

package/dist/repository.js

@@ -1,11 +1,13 @@
 import { QuadPatchConflictError, encodeTerm, decodeTerm, prepareQuadPatch, } from '@gnolith/diamond';
 import { DataFactory } from 'rdf-data-factory';
-import { cloneEntity, entityNumericId, exportEntityJson, MAX_ENTITY_BYTES, parseEntityJson, validateEntity, validateSnak, } from './canonical.js';
-import { EntityAlreadyExistsError, EntityNotFoundError, InvalidEntityError, InvalidStatementError, InvalidCursorError, BulkLimitError, PropertyDatatypeMismatchError, PropertyNotFoundError, QuadPatchTooLargeError, RevisionConflictError, SchemaMismatchError, } from './errors.js';
+import { cloneEntity, assertAuthoredStatementText, entityNumericId, exportEntityJson, MAX_ENTITY_BYTES, parseEntityJson, validateEntity, validateSnak, } from './canonical.js';
+import { EntityAlreadyExistsError, AuthorizationDeniedError, EntityNotFoundError, InvalidEntityError, InvalidStatementError, InvalidCursorError, BulkLimitError, PropertyDatatypeMismatchError, PropertyNotFoundError, QuadPatchTooLargeError, RevisionConflictError, SchemaMismatchError, } from './errors.js';
 import { buildEntityQuads } from './rdf.js';
 import { withoutTrailingSlashes } from './iri.js';
 import { canonicalizeTaprootBaseIri } from './migrations.js';
 import { TAPROOT_RDF_VERSION } from './schema.js';
+import { intersectVisibilityScopes, isVisibleTo, normalizeCanonicalAuthorizationPolicy, normalizeAuthorizationContext, normalizeVisibilityScope, serializeVisibilityScope, KNOWLEDGE_POLICY_CAPABILITY, KNOWLEDGE_WRITE_CAPABILITY, } from './authorization.js';
+/** Package-internal persistence implementation. Not exported by the package. */
 export class TaprootRepository {
     #db;
     #options;
@@ -29,6 +31,79 @@ export class TaprootRepository {
             ...(options.factory ? { factory: options.factory } : {}),
         };
     }
+    /** Assembly-only pristine bootstrap. Canonical writes remain policy-bound. */
+    async bootstrapAuthorization(installationId) {
+        if (typeof installationId !== 'string' ||
+            !installationId.trim() ||
+            installationId.length > 256)
+            throw new InvalidEntityError('installationId must contain 1 through 256 characters');
+        const createdAt = this.#options.clock().toISOString();
+        try {
+            await this.#db.batch([
+                this.#assertion(`NOT EXISTS (SELECT 1 FROM taproot_entities)`),
+                this.#db
+                    .prepare(`INSERT INTO taproot_installation_authorization(
+               singleton, installation_id, authorization_revision,
+               search_generation, last_advance_id, created_at, updated_at
+             ) VALUES (1, ?, 1, 1, 'bootstrap', ?, ?)`)
+                    .bind(installationId, createdAt, createdAt),
+            ]);
+        }
+        catch (cause) {
+            throw new RevisionConflictError('Authorization bootstrap requires a pristine uninitialized installation', { cause: toError(cause) });
+        }
+    }
+    /** Explicit bootstrap for a fully quarantined pre-0004 installation. */
+    async bootstrapLegacyAuthorization(installationId, attestation) {
+        if (typeof installationId !== 'string' ||
+            !installationId.trim() ||
+            installationId.length > 256)
+            throw new InvalidEntityError('installationId must contain 1 through 256 characters');
+        if (!Number.isSafeInteger(attestation.entityCount) ||
+            attestation.entityCount < 1 ||
+            !Number.isSafeInteger(attestation.revisionCount) ||
+            attestation.revisionCount < attestation.entityCount ||
+            !/^[a-f0-9]{64}$/u.test(attestation.revisionManifestHash))
+            throw new InvalidEntityError('Legacy authorization attestation is invalid');
+        const counts = await this.#db
+            .prepare(`SELECT
+           (SELECT COUNT(*) FROM taproot_entities) AS entity_count,
+           (SELECT COUNT(*) FROM taproot_entity_revisions) AS revision_count,
+           (SELECT COUNT(*) FROM taproot_entity_authorization) AS policy_count`)
+            .all();
+        const count = counts.results[0];
+        const revisions = await this.#db
+            .prepare(`SELECT entity_id, revision, content_hash
+         FROM taproot_entity_revisions ORDER BY entity_id, revision`)
+            .all();
+        const manifestHash = await sha256(JSON.stringify(revisions.results.map(({ entity_id, revision, content_hash }) => [
+            entity_id,
+            Number(revision),
+            content_hash,
+        ])));
+        if (Number(count?.entity_count ?? 0) !== attestation.entityCount ||
+            Number(count?.revision_count ?? 0) !== attestation.revisionCount ||
+            Number(count?.policy_count ?? 0) !== 0 ||
+            manifestHash !== attestation.revisionManifestHash)
+            throw new RevisionConflictError('Legacy authorization attestation does not match quarantined canonical state');
+        const createdAt = this.#options.clock().toISOString();
+        try {
+            await this.#db.batch([
+                this.#assertion(`(SELECT COUNT(*) FROM taproot_entities) = ?
+           AND (SELECT COUNT(*) FROM taproot_entity_revisions) = ?
+           AND NOT EXISTS (SELECT 1 FROM taproot_entity_authorization)`, attestation.entityCount, attestation.revisionCount),
+                this.#db
+                    .prepare(`INSERT INTO taproot_installation_authorization(
+               singleton, installation_id, authorization_revision,
+               search_generation, last_advance_id, created_at, updated_at
+             ) VALUES (1, ?, 1, 1, 'legacy-bootstrap', ?, ?)`)
+                    .bind(installationId, createdAt, createdAt),
+            ]);
+        }
+        catch (cause) {
+            throw new RevisionConflictError('Legacy authorization bootstrap lost its state attestation race', { cause: toError(cause) });
+        }
+    }
     async getEntity(id) {
         const row = await this.#loadRow(id);
         if (!row)
@@ -265,11 +340,15 @@ export class TaprootRepository {
     async replaceEntity(id, replacement, edit) {
         if (replacement.id !== id)
             throw new InvalidEntityError('Replacement entity id cannot change');
-        return this.#mutate(id, edit, () => cloneEntity(replacement), undefined, 'update');
+        return this.#mutate(id, edit, () => resupplyStatementTexts(cloneEntity(replacement), edit.statementTexts), undefined, 'update');
     }
     async revertEntity(id, targetRevision, edit) {
+        if (edit.authorization || edit.authorizationContext)
+            await this.#preauthorizeCanonicalWrite(id, edit.authorization, edit.authorizationContext, edit.expectedRevision);
         const target = await this.getEntityRevision(id, targetRevision);
-        return this.#mutate(id, edit, () => cloneEntity(target.entity), { deletedAt: target.deletedAt, redirectTo: target.redirectTo }, 'revert');
+        if (target.redirectTo)
+            await this.#validateRedirectTarget(id, target.redirectTo, target.entity.type, edit.authorizationContext);
+        return this.#mutate(id, edit, () => resupplyStatementTexts(cloneEntity(target.entity), edit.statementTexts), { deletedAt: target.deletedAt, redirectTo: target.redirectTo }, 'revert');
     }
     async softDeleteEntity(id, edit) {
         return this.#mutate(id, edit, (entity) => entity, {
@@ -286,22 +365,16 @@ export class TaprootRepository {
     async redirectEntity(id, target, edit) {
         if (id === target)
             throw new InvalidEntityError('An entity cannot redirect to itself');
-        const source = await this.getEntity(id);
-        const targetEntity = await this.getEntity(target);
-        if (source.entity.type !== targetEntity.entity.type)
-            throw new InvalidEntityError('Redirect source and target must have the same entity type');
-        if (targetEntity.deletedAt)
-            throw new InvalidEntityError('An entity cannot redirect to a deleted target');
-        const seen = new Set([id]);
-        let cursor = target;
-        for (let depth = 0; cursor && depth < 100; depth += 1) {
-            if (seen.has(cursor))
-                throw new InvalidEntityError('Redirect would create a cycle');
-            seen.add(cursor);
-            cursor = (await this.getEntity(cursor)).redirectTo;
-        }
-        if (cursor)
-            throw new InvalidEntityError('Redirect chain exceeds 100 entities');
+        if (edit.authorization || edit.authorizationContext)
+            await this.#preauthorizeCanonicalWrite(id, edit.authorization, edit.authorizationContext, edit.expectedRevision);
+        const source = edit.authorizationContext
+            ? await this.#authorizedLifecycle(id, edit.authorizationContext)
+            : await this.getEntity(id).then(({ entity, deletedAt, redirectTo }) => ({
+                type: entity.type,
+                deletedAt,
+                redirectTo,
+            }));
+        await this.#validateRedirectTarget(id, target, source.type, edit.authorizationContext);
         return this.#mutate(id, edit, (entity) => entity, {
             deletedAt: null,
             redirectTo: target,
@@ -366,6 +439,7 @@ export class TaprootRepository {
         });
     }
     async addStatement(id, statement, edit) {
+        assertAuthoredStatementText(statement.text, statement.id);
         return this.#mutate(id, edit, (entity) => {
             const property = statement.mainsnak.property;
             entity.claims[property] ??= [];
@@ -374,6 +448,7 @@ export class TaprootRepository {
         });
     }
     async replaceStatement(id, statementId, statement, edit) {
+        assertAuthoredStatementText(statement.text, statement.id);
         return this.#mutate(id, edit, (entity) => {
             const located = locateStatement(entity, statementId);
             located.statements.splice(located.index, 1);
@@ -394,16 +469,21 @@ export class TaprootRepository {
             return entity;
         });
     }
-    async setStatementRank(id, statementId, rank, edit) {
+    async setStatementRank(id, statementId, rank, text, edit) {
+        assertAuthoredStatementText(text, statementId);
         return this.#mutate(id, edit, (entity) => {
-            locateStatement(entity, statementId).statement.rank = rank;
+            const statement = locateStatement(entity, statementId).statement;
+            statement.rank = rank;
+            statement.text = text;
             return entity;
         });
     }
-    async addQualifier(id, statementId, snak, edit) {
+    async addQualifier(id, statementId, snak, text, edit) {
+        assertAuthoredStatementText(text, statementId);
         validateSnak(snak);
         return this.#mutate(id, edit, (entity) => {
             const statement = locateStatement(entity, statementId).statement;
+            statement.text = text;
             const property = snak.property;
             if (!statement.qualifiers[property]) {
                 statement.qualifiers[property] = [];
@@ -413,9 +493,11 @@ export class TaprootRepository {
             return entity;
         });
     }
-    async removeQualifier(id, statementId, property, ordinal, edit) {
+    async removeQualifier(id, statementId, property, ordinal, text, edit) {
+        assertAuthoredStatementText(text, statementId);
         return this.#mutate(id, edit, (entity) => {
             const statement = locateStatement(entity, statementId).statement;
+            statement.text = text;
             const snaks = statement.qualifiers[property];
             if (!snaks?.[ordinal])
                 throw new InvalidStatementError('Qualifier does not exist');
@@ -427,16 +509,21 @@ export class TaprootRepository {
             return entity;
         });
     }
-    async addReference(id, statementId, reference, edit) {
+    async addReference(id, statementId, reference, text, edit) {
+        assertAuthoredStatementText(text, statementId);
         return this.#mutate(id, edit, (entity) => {
-            locateStatement(entity, statementId).statement.references.push(structuredClone(reference));
+            const statement = locateStatement(entity, statementId).statement;
+            statement.text = text;
+            statement.references.push(structuredClone(reference));
             return entity;
         });
     }
-    async removeReference(id, statementId, hash, edit) {
+    async removeReference(id, statementId, hash, text, edit) {
+        assertAuthoredStatementText(text, statementId);
         return this.#mutate(id, edit, (entity) => {
-            const references = locateStatement(entity, statementId).statement
-                .references;
+            const statement = locateStatement(entity, statementId).statement;
+            statement.text = text;
+            const references = statement.references;
             const index = references.findIndex((reference) => reference.hash === hash);
             if (index < 0)
                 throw new InvalidStatementError(`Reference ${hash} does not exist`);
@@ -444,10 +531,12 @@ export class TaprootRepository {
             return entity;
         });
     }
-    async replaceReference(id, statementId, hash, reference, edit) {
+    async replaceReference(id, statementId, hash, reference, text, edit) {
+        assertAuthoredStatementText(text, statementId);
         return this.#mutate(id, edit, (entity) => {
-            const references = locateStatement(entity, statementId).statement
-                .references;
+            const statement = locateStatement(entity, statementId).statement;
+            statement.text = text;
+            const references = statement.references;
             const index = references.findIndex((item) => item.hash === hash);
             if (index < 0)
                 throw new InvalidStatementError(`Reference ${hash} does not exist`);
@@ -462,6 +551,7 @@ export class TaprootRepository {
         }
         const succeeded = new Map();
         const failed = [];
+        let authorizationContext = options.metadata?.authorizationContext;
         let pending = values
             .map((entity, index) => ({ entity, index }))
             .sort((a, b) => Number(a.entity.type !== 'property') -
@@ -471,7 +561,20 @@ export class TaprootRepository {
             let progress = false;
             for (const entry of pending) {
                 try {
-                    succeeded.set(entry.index, await this.#importOne(entry.entity, options));
+                    const effectiveOptions = authorizationContext
+                        ? {
+                            ...options,
+                            metadata: { ...options.metadata, authorizationContext },
+                        }
+                        : options;
+                    const result = await this.#importOne(entry.entity, effectiveOptions);
+                    succeeded.set(entry.index, result);
+                    if (authorizationContext &&
+                        result.authorizationRevision !== undefined)
+                        authorizationContext = {
+                            ...authorizationContext,
+                            authorizationRevision: result.authorizationRevision,
+                        };
                     progress = true;
                 }
                 catch (error) {
@@ -518,11 +621,31 @@ export class TaprootRepository {
     }
     async #importOne(entity, options) {
         if (options.mode === 'upsert') {
+            const authorization = options.authorizations?.[entity.id];
+            const authorizationContext = options.metadata?.authorizationContext;
+            if (authorization || authorizationContext) {
+                const currentRevision = await this.#preauthorizeCanonicalWrite(entity.id, authorization, authorizationContext);
+                if (currentRevision !== null)
+                    return this.replaceEntity(entity.id, entity, {
+                        expectedRevision: currentRevision,
+                        statementTexts: authoredStatementTexts(entity),
+                        ...options.metadata,
+                        ...(authorization ? { authorization } : {}),
+                    });
+                return this.importEntity(entity, {
+                    ...options.metadata,
+                    ...(authorization ? { authorization } : {}),
+                });
+            }
             try {
                 const current = await this.getEntity(entity.id);
                 return await this.replaceEntity(entity.id, entity, {
                     expectedRevision: current.entity.lastrevid,
+                    statementTexts: authoredStatementTexts(entity),
                     ...options.metadata,
+                    ...(options.authorizations?.[entity.id]
+                        ? { authorization: options.authorizations[entity.id] }
+                        : {}),
                 });
             }
             catch (error) {
@@ -530,7 +653,12 @@ export class TaprootRepository {
                     throw error;
             }
         }
-        return this.importEntity(entity, options.metadata);
+        return this.importEntity(entity, {
+            ...options.metadata,
+            ...(options.authorizations?.[entity.id]
+                ? { authorization: options.authorizations[entity.id] }
+                : {}),
+        });
     }
     async applyCommands(id, commands, edit) {
         if (!commands.length)
@@ -721,12 +849,48 @@ export class TaprootRepository {
             deletedAt: stored.deletedAt,
             redirectTo: stored.redirectTo,
         });
+        const authorization = await this.#db
+            .prepare(`SELECT s.installation_id, s.authorization_revision, s.search_generation,
+                s.last_advance_id
+         FROM taproot_installation_authorization s
+         JOIN taproot_entity_authorization p
+           ON p.installation_id = s.installation_id
+         WHERE s.singleton = 1 AND p.entity_id = ?
+           AND p.source_revision = ?`)
+            .bind(id, stored.entity.lastrevid)
+            .all();
+        const authorizationState = authorization.results[0];
+        if (!authorizationState)
+            throw new RevisionConflictError('Projection repair requires current canonical authorization policy');
+        const nextSearchGeneration = Number(authorizationState.search_generation) + 1;
         const statements = [
             this.#db
                 .prepare(`DELETE FROM taproot_terms WHERE entity_id = ?`)
                 .bind(id),
             this.#termsInsert(stored.entity),
             this.#auditInsert(stored.entity, metadata, context),
+            this.#db
+                .prepare(`UPDATE taproot_installation_authorization
+           SET search_generation = ?, last_advance_id = ?, updated_at = ?
+           WHERE singleton = 1 AND installation_id = ?
+             AND authorization_revision = ? AND search_generation = ?
+             AND last_advance_id = ?`)
+                .bind(nextSearchGeneration, context.eventId, context.createdAt, authorizationState.installation_id, authorizationState.authorization_revision, authorizationState.search_generation, authorizationState.last_advance_id),
+            this.#assertion(`EXISTS (
+           SELECT 1 FROM taproot_installation_authorization s
+           JOIN taproot_entity_authorization p
+             ON p.installation_id = s.installation_id
+            WHERE s.singleton = 1 AND p.entity_id = ?
+              AND p.source_revision = ? AND s.authorization_revision = ?
+              AND s.search_generation = ?
+              AND s.last_advance_id = ?
+          )`, id, stored.entity.lastrevid, authorizationState.authorization_revision, nextSearchGeneration, context.eventId),
+            this.#db
+                .prepare(`INSERT INTO taproot_authorization_projection_outbox(
+             event_id, entity_id, source_revision, authorization_revision,
+             search_generation, operation, created_at
+           ) VALUES (?, ?, ?, ?, ?, 'repair', ?)`)
+                .bind(context.eventId, id, stored.entity.lastrevid, authorizationState.authorization_revision, nextSearchGeneration, context.createdAt),
             ...patch.statements,
             ...this.#ownershipPatch(id, actual, expected).statements,
         ];
@@ -738,6 +902,8 @@ export class TaprootRepository {
             this.#emitObservation('repair', started, 'error', id, stored.entity.lastrevid, cause);
             if (isEventIdUniqueError(cause))
                 throw new RevisionConflictError('Generated audit event id already exists', { cause });
+            if (isAssertionError(cause))
+                throw new RevisionConflictError('Canonical policy changed during projection repair', { cause });
             throw cause;
         }
         const after = await this.inspectEntityIntegrity(id);
@@ -752,6 +918,8 @@ export class TaprootRepository {
     async #create(entity, metadata, allocated, eventType) {
         const started = performance.now();
         validateEntity(entity);
+        if (metadata.authorization || metadata.authorizationContext)
+            await this.#preauthorizeCanonicalWrite(entity.id, metadata.authorization, metadata.authorizationContext);
         if (await this.#loadRow(entity.id))
             throw new EntityAlreadyExistsError(`Entity ${entity.id} already exists`);
         await this.#validatePropertyDatatypes(entity);
@@ -759,6 +927,9 @@ export class TaprootRepository {
         const json = exportEntityJson(entity, this.#options.maxEntityBytes);
         const lifecycle = { deletedAt: null, redirectTo: null };
         const context = await this.#writeContext(entity, json, metadata, null, eventType, lifecycle);
+        const authorization = metadata.authorization
+            ? await this.#prepareAuthorizationWrite(entity, metadata.authorization, metadata.authorizationContext, undefined)
+            : undefined;
         const newQuads = this.#lifecycleQuads(entity, lifecycle);
         const marker = revisionQuad(entity, this.#options);
         const patch = this.#preparePatch({ forbid: [marker], insert: newQuads });
@@ -777,7 +948,9 @@ export class TaprootRepository {
         }
         statements.push(this.#db
             .prepare(`INSERT INTO taproot_entities(entity_id, entity_type, datatype, revision, entity_json, modified_at) VALUES (?, ?, ?, ?, ?, ?)`)
-            .bind(entity.id, entity.type, entity.type === 'property' ? entity.datatype : null, entity.lastrevid, json, entity.modified), this.#revisionInsert(entity, json, metadata, context), this.#auditInsert(entity, metadata, context), this.#termsInsert(entity));
+            .bind(entity.id, entity.type, entity.type === 'property' ? entity.datatype : null, entity.lastrevid, json, entity.modified), this.#revisionInsert(entity, json, metadata, context), this.#auditInsert(entity, metadata, context, authorization), this.#termsInsert(entity));
+        if (authorization)
+            statements.push(...this.#authorizationWriteStatements(entity, lifecycle, context, authorization, undefined));
         const patchOffset = statements.length;
         statements.push(...patch.statements);
         const ownership = this.#ownershipPatch(entity.id, [], newQuads);
@@ -796,6 +969,12 @@ export class TaprootRepository {
                 },
                 eventId: context.eventId,
                 contentHash: context.contentHash,
+                ...(authorization
+                    ? {
+                        authorizationRevision: authorization.authorizationRevision,
+                        searchGeneration: authorization.searchGeneration,
+                    }
+                    : {}),
             };
             this.#emitObservation(eventType, started, 'success', entity.id, entity.lastrevid);
             return result;
@@ -812,13 +991,17 @@ export class TaprootRepository {
             }
             if (isEventIdUniqueError(mapped))
                 throw new RevisionConflictError('Generated audit event id already exists', { cause: mapped });
-            if (allocated && isAssertionError(mapped))
-                throw new RevisionConflictError(`ID allocation for ${entity.id} was stale`, { cause: mapped });
+            if (isAssertionError(mapped))
+                throw new RevisionConflictError(allocated
+                    ? `ID allocation for ${entity.id} was stale`
+                    : `Authorization state changed while creating ${entity.id}`, { cause: mapped });
             throw mapped;
         }
     }
     async #mutate(id, edit, transform, lifecycleOverride, eventType = 'update') {
         const started = performance.now();
+        if (edit.authorization || edit.authorizationContext)
+            await this.#preauthorizeCanonicalWrite(id, edit.authorization, edit.authorizationContext, edit.expectedRevision);
         const row = await this.#loadRow(id);
         if (!row)
             throw new EntityNotFoundError(`Entity ${id} was not found`);
@@ -850,6 +1033,9 @@ export class TaprootRepository {
             (await revisionContentHash(row.entity_json, oldLifecycle));
         const newLifecycle = lifecycleOverride ?? oldLifecycle;
         const context = await this.#writeContext(next, json, edit, parentHash, eventType, newLifecycle);
+        const authorization = edit.authorization
+            ? await this.#prepareAuthorizationWrite(next, edit.authorization, edit.authorizationContext, previous)
+            : undefined;
         const oldQuads = this.#lifecycleQuads(stored.entity, oldLifecycle);
         const newQuads = this.#lifecycleQuads(next, newLifecycle);
         const patch = this.#preparePatch({
@@ -863,12 +1049,14 @@ export class TaprootRepository {
                 .bind(next.type === 'property' ? next.datatype : null, next.lastrevid, json, next.modified, newLifecycle.deletedAt, newLifecycle.redirectTo, id, previous),
             this.#assertion(`EXISTS (SELECT 1 FROM taproot_entities WHERE entity_id = ? AND revision = ?)`, id, next.lastrevid),
             this.#revisionInsert(next, json, edit, context),
-            this.#auditInsert(next, edit, context),
+            this.#auditInsert(next, edit, context, authorization),
             this.#db
                 .prepare('DELETE FROM taproot_terms WHERE entity_id = ?')
                 .bind(id),
             this.#termsInsert(next),
         ];
+        if (authorization)
+            statements.push(...this.#authorizationWriteStatements(next, newLifecycle, context, authorization, previous));
         const patchOffset = statements.length;
         statements.push(...patch.statements);
         const ownership = this.#ownershipPatch(id, oldQuads, newQuads);
@@ -887,6 +1075,12 @@ export class TaprootRepository {
                 },
                 eventId: context.eventId,
                 contentHash: context.contentHash,
+                ...(authorization
+                    ? {
+                        authorizationRevision: authorization.authorizationRevision,
+                        searchGeneration: authorization.searchGeneration,
+                    }
+                    : {}),
             };
             this.#emitObservation(eventType, started, 'success', id, next.lastrevid);
             return result;
@@ -907,6 +1101,295 @@ export class TaprootRepository {
             throw mapped;
         }
     }
+    async #prepareAuthorizationWrite(entity, rawPolicy, rawContext, previousRevision) {
+        const policy = normalizeCanonicalAuthorizationPolicy(rawPolicy);
+        if (!rawContext)
+            throw new InvalidEntityError('Guarded canonical writes require AuthorizationContext');
+        const caller = normalizeAuthorizationContext(rawContext);
+        if (!caller.capabilities.includes(KNOWLEDGE_WRITE_CAPABILITY))
+            throw new InvalidEntityError(`Canonical writes require ${KNOWLEDGE_WRITE_CAPABILITY}`);
+        const expectedStatementIds = statementIds(entity);
+        const providedStatementIds = Object.keys(policy.statementRestrictions).sort(compareCodeUnits);
+        if (JSON.stringify(expectedStatementIds) !==
+            JSON.stringify(providedStatementIds))
+            throw new InvalidEntityError('statementRestrictions must explicitly and exactly cover the post-mutation statements');
+        const state = await this.#db
+            .prepare(`SELECT installation_id, authorization_revision, search_generation,
+              last_advance_id
+         FROM taproot_installation_authorization WHERE singleton = 1`)
+            .all();
+        const installation = state.results[0];
+        if (!installation ||
+            installation.installation_id !== policy.installationId ||
+            Number(installation.authorization_revision) !==
+                policy.expectedAuthorizationRevision ||
+            caller.installationId !== policy.installationId ||
+            caller.authorizationRevision !== policy.expectedAuthorizationRevision)
+            throw new RevisionConflictError('Installation authorization revision is stale or mismatched');
+        if (policy.workspaceId !== null &&
+            !caller.workspaceIds.includes(policy.workspaceId))
+            throw new InvalidEntityError('Canonical policy workspace must belong to the caller context');
+        if (!isVisibleTo(policy.visibility, caller))
+            throw new InvalidEntityError('Canonical policy must remain visible to its creating or updating caller');
+        if (previousRevision === undefined &&
+            policy.ownerPrincipalId !== caller.principalId &&
+            !caller.capabilities.includes(KNOWLEDGE_POLICY_CAPABILITY))
+            throw new InvalidEntityError(`Creating policy for another owner requires ${KNOWLEDGE_POLICY_CAPABILITY}`);
+        const statementRows = expectedStatementIds.map((statementId) => {
+            const restrictions = policy.statementRestrictions[statementId];
+            return {
+                statementId,
+                restrictionsJson: JSON.stringify(restrictions),
+                effectiveVisibilityJson: serializeVisibilityScope(intersectVisibilityScopes(policy.visibility, ...restrictions)),
+            };
+        });
+        const effectiveVisibilityJson = serializeVisibilityScope(intersectVisibilityScopes(policy.visibility, ...statementRows.map(({ effectiveVisibilityJson: serialized }) => JSON.parse(serialized))));
+        let action = 'create';
+        if (previousRevision !== undefined) {
+            const current = await this.#db
+                .prepare(`SELECT installation_id, source_revision, visibility_json,
+                  effective_visibility_json, workspace_id, owner_principal_id
+           FROM taproot_entity_authorization WHERE entity_id = ?`)
+                .bind(entity.id)
+                .all();
+            const previousPolicy = current.results[0];
+            if (!previousPolicy ||
+                previousPolicy.installation_id !== policy.installationId ||
+                Number(previousPolicy.source_revision) !== previousRevision)
+                throw new RevisionConflictError('Canonical entity policy is missing, quarantined, or stale');
+            assertScopeDoesNotWiden(policy.visibility, JSON.parse(previousPolicy.visibility_json), 'entity visibility');
+            if (!isVisibleTo(JSON.parse(previousPolicy.effective_visibility_json), caller))
+                throw new InvalidEntityError('Caller is not authorized for the current canonical policy');
+            const previousStatements = await this.#db
+                .prepare(`SELECT statement_id, restrictions_json, effective_visibility_json
+           FROM taproot_statement_authorization
+           WHERE entity_id = ? AND source_revision = ?`)
+                .bind(entity.id, previousRevision)
+                .all();
+            const nextById = new Map(statementRows.map((row) => [row.statementId, row]));
+            const previousRestrictions = Object.fromEntries(previousStatements.results
+                .map((row) => {
+                const parsed = JSON.parse(row.restrictions_json);
+                if (!Array.isArray(parsed))
+                    throw new InvalidEntityError(`Stored statement ${row.statement_id} restrictions are invalid`);
+                return [
+                    row.statement_id,
+                    parsed.map((scope) => normalizeVisibilityScope(scope)),
+                ];
+            })
+                .sort(([left], [right]) => compareCodeUnits(String(left), String(right))));
+            for (const previous of previousStatements.results) {
+                const next = nextById.get(previous.statement_id);
+                if (!next)
+                    continue;
+                assertScopeDoesNotWiden(JSON.parse(next.effectiveVisibilityJson), JSON.parse(previous.effective_visibility_json), `statement ${previous.statement_id} visibility`);
+            }
+            const changed = previousPolicy.workspace_id !== policy.workspaceId ||
+                previousPolicy.owner_principal_id !== policy.ownerPrincipalId ||
+                previousPolicy.visibility_json !==
+                    serializeVisibilityScope(policy.visibility) ||
+                JSON.stringify(previousRestrictions) !==
+                    JSON.stringify(policy.statementRestrictions);
+            action = changed ? 'policy-change' : 'unchanged';
+            if (changed && !caller.capabilities.includes(KNOWLEDGE_POLICY_CAPABILITY))
+                throw new InvalidEntityError(`Canonical policy changes require ${KNOWLEDGE_POLICY_CAPABILITY}`);
+        }
+        const authorizationRevision = policy.expectedAuthorizationRevision + 1;
+        const searchGeneration = Number(installation.search_generation) + 1;
+        if (!Number.isSafeInteger(authorizationRevision) ||
+            !Number.isSafeInteger(searchGeneration))
+            throw new RevisionConflictError('Installation authorization counters are exhausted');
+        return {
+            policy,
+            previousAdvanceId: installation.last_advance_id,
+            authorizationRevision,
+            searchGeneration,
+            effectiveVisibilityJson,
+            action,
+            statementRows,
+        };
+    }
+    async #preauthorizeCanonicalWrite(entityId, rawPolicy, rawContext, expectedRevision) {
+        if (!rawPolicy || !rawContext)
+            throw new AuthorizationDeniedError('Authorization denied');
+        let policy;
+        let caller;
+        try {
+            policy = normalizeCanonicalAuthorizationPolicy(rawPolicy);
+            caller = normalizeAuthorizationContext(rawContext);
+        }
+        catch {
+            throw new AuthorizationDeniedError('Authorization denied');
+        }
+        if (!caller.capabilities.includes(KNOWLEDGE_WRITE_CAPABILITY))
+            throw new AuthorizationDeniedError('Authorization denied');
+        const result = await this.#db
+            .prepare(`SELECT s.installation_id, s.authorization_revision,
+                e.entity_id, e.revision,
+                p.installation_id AS policy_installation_id,
+                p.source_revision AS policy_source_revision,
+                p.effective_visibility_json
+         FROM taproot_installation_authorization s
+         LEFT JOIN taproot_entities e ON e.entity_id = ?
+         LEFT JOIN taproot_entity_authorization p
+           ON p.entity_id = e.entity_id AND p.source_revision = e.revision
+         WHERE s.singleton = 1`)
+            .bind(entityId)
+            .all();
+        const row = result.results[0];
+        if (!row ||
+            row.installation_id !== policy.installationId ||
+            row.installation_id !== caller.installationId ||
+            Number(row.authorization_revision) !==
+                policy.expectedAuthorizationRevision ||
+            Number(row.authorization_revision) !== caller.authorizationRevision)
+            throw new AuthorizationDeniedError('Authorization denied');
+        if (row.entity_id === null) {
+            if (expectedRevision !== undefined)
+                throw new AuthorizationDeniedError('Authorization denied');
+            if ((policy.workspaceId !== null &&
+                !caller.workspaceIds.includes(policy.workspaceId)) ||
+                !isVisibleTo(policy.visibility, caller) ||
+                (policy.ownerPrincipalId !== caller.principalId &&
+                    !caller.capabilities.includes(KNOWLEDGE_POLICY_CAPABILITY)))
+                throw new AuthorizationDeniedError('Authorization denied');
+            return null;
+        }
+        if (row.policy_installation_id !== row.installation_id ||
+            row.policy_source_revision === null ||
+            row.effective_visibility_json === null ||
+            !isVisibleTo(JSON.parse(row.effective_visibility_json), caller))
+            throw new AuthorizationDeniedError('Authorization denied');
+        if (expectedRevision !== undefined &&
+            Number(row.policy_source_revision) !== expectedRevision)
+            throw new RevisionConflictError('Canonical revision is stale');
+        return Number(row.policy_source_revision);
+    }
+    async #authorizedLifecycle(entityId, rawContext) {
+        const caller = normalizeAuthorizationContext(rawContext);
+        if (!caller.capabilities.includes(KNOWLEDGE_WRITE_CAPABILITY))
+            throw new AuthorizationDeniedError('Authorization denied');
+        const result = await this.#db
+            .prepare(`SELECT e.entity_type, e.deleted_at, e.redirect_to,
+                p.effective_visibility_json
+         FROM taproot_installation_authorization s
+         JOIN taproot_entities e ON e.entity_id = ?
+         JOIN taproot_entity_authorization p
+           ON p.entity_id = e.entity_id AND p.source_revision = e.revision
+         WHERE s.singleton = 1
+           AND s.installation_id = ? AND s.authorization_revision = ?
+           AND p.installation_id = s.installation_id`)
+            .bind(entityId, caller.installationId, caller.authorizationRevision)
+            .all();
+        const row = result.results[0];
+        if (!row ||
+            !isVisibleTo(JSON.parse(row.effective_visibility_json), caller))
+            throw new AuthorizationDeniedError('Authorization denied');
+        return {
+            type: row.entity_type,
+            deletedAt: row.deleted_at,
+            redirectTo: row.redirect_to,
+        };
+    }
+    async #validateRedirectTarget(sourceId, targetId, sourceType, authorizationContext) {
+        const seen = new Set([sourceId]);
+        let cursor = targetId;
+        for (let depth = 0; cursor && depth < 100; depth += 1) {
+            if (seen.has(cursor))
+                throw new InvalidEntityError('Redirect would create a cycle');
+            seen.add(cursor);
+            const target = authorizationContext
+                ? await this.#authorizedLifecycle(cursor, authorizationContext)
+                : await this.getEntity(cursor).then(({ entity, deletedAt, redirectTo }) => ({
+                    type: entity.type,
+                    deletedAt,
+                    redirectTo,
+                }));
+            if (target.type !== sourceType)
+                throw new InvalidEntityError('Redirect source and target must have the same entity type');
+            if (target.deletedAt)
+                throw new InvalidEntityError('An entity cannot redirect to a deleted target');
+            cursor = target.redirectTo;
+        }
+        if (cursor)
+            throw new InvalidEntityError('Redirect chain exceeds 100 entities');
+    }
+    #authorizationWriteStatements(entity, lifecycle, context, prepared, previousRevision) {
+        const { policy, authorizationRevision, searchGeneration, effectiveVisibilityJson, statementRows, previousAdvanceId, } = prepared;
+        const visibilityJson = serializeVisibilityScope(policy.visibility);
+        const rowsJson = JSON.stringify(statementRows);
+        const statements = [
+            this.#db
+                .prepare(`UPDATE taproot_installation_authorization
+           SET authorization_revision = ?, search_generation = ?, updated_at = ?
+               , last_advance_id = ?
+           WHERE singleton = 1 AND installation_id = ?
+             AND authorization_revision = ? AND search_generation = ?
+             AND last_advance_id = ?`)
+                .bind(authorizationRevision, searchGeneration, context.createdAt, context.eventId, policy.installationId, policy.expectedAuthorizationRevision, searchGeneration - 1, previousAdvanceId),
+            this.#assertion(`EXISTS (
+           SELECT 1 FROM taproot_installation_authorization
+           WHERE singleton = 1 AND installation_id = ?
+             AND authorization_revision = ? AND search_generation = ?
+             AND last_advance_id = ?
+         )`, policy.installationId, authorizationRevision, searchGeneration, context.eventId),
+        ];
+        if (previousRevision === undefined) {
+            statements.push(this.#db
+                .prepare(`INSERT INTO taproot_entity_authorization(
+               entity_id, installation_id, workspace_id, owner_principal_id,
+               visibility_json, effective_visibility_json, source_revision, authorization_revision,
+               deleted_at, event_id, updated_at
+             ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .bind(entity.id, policy.installationId, policy.workspaceId, policy.ownerPrincipalId, visibilityJson, effectiveVisibilityJson, entity.lastrevid, authorizationRevision, lifecycle.deletedAt, context.eventId, context.createdAt));
+        }
+        else {
+            statements.push(this.#db
+                .prepare(`UPDATE taproot_entity_authorization
+             SET workspace_id = ?, owner_principal_id = ?, visibility_json = ?,
+                 effective_visibility_json = ?, source_revision = ?, authorization_revision = ?, deleted_at = ?,
+                 event_id = ?, updated_at = ?
+             WHERE entity_id = ? AND installation_id = ? AND source_revision = ?`)
+                .bind(policy.workspaceId, policy.ownerPrincipalId, visibilityJson, effectiveVisibilityJson, entity.lastrevid, authorizationRevision, lifecycle.deletedAt, context.eventId, context.createdAt, entity.id, policy.installationId, previousRevision), this.#assertion(`EXISTS (
+             SELECT 1 FROM taproot_entity_authorization
+             WHERE entity_id = ? AND installation_id = ?
+               AND source_revision = ? AND authorization_revision = ?
+           )`, entity.id, policy.installationId, entity.lastrevid, authorizationRevision));
+        }
+        statements.push(this.#db
+            .prepare(`INSERT INTO taproot_entity_authorization_revisions(
+             entity_id, source_revision, installation_id, workspace_id,
+             owner_principal_id, visibility_json, effective_visibility_json, authorization_revision,
+             deleted_at, event_id, created_at
+           ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .bind(entity.id, entity.lastrevid, policy.installationId, policy.workspaceId, policy.ownerPrincipalId, visibilityJson, effectiveVisibilityJson, authorizationRevision, lifecycle.deletedAt, context.eventId, context.createdAt), this.#db
+            .prepare(`DELETE FROM taproot_statement_authorization WHERE entity_id = ?`)
+            .bind(entity.id), this.#db
+            .prepare(`INSERT INTO taproot_statement_authorization(
+             entity_id, statement_id, source_revision, restrictions_json,
+             effective_visibility_json, authorization_revision
+           )
+           SELECT ?, json_extract(value, '$.statementId'), ?,
+             json_extract(value, '$.restrictionsJson'),
+             json_extract(value, '$.effectiveVisibilityJson'), ?
+           FROM json_each(?)`)
+            .bind(entity.id, entity.lastrevid, authorizationRevision, rowsJson), this.#db
+            .prepare(`INSERT INTO taproot_statement_authorization_revisions(
+             entity_id, source_revision, statement_id, restrictions_json,
+             effective_visibility_json, authorization_revision
+           )
+           SELECT ?, ?, json_extract(value, '$.statementId'),
+             json_extract(value, '$.restrictionsJson'),
+             json_extract(value, '$.effectiveVisibilityJson'), ?
+           FROM json_each(?)`)
+            .bind(entity.id, entity.lastrevid, authorizationRevision, rowsJson), this.#db
+            .prepare(`INSERT INTO taproot_authorization_projection_outbox(
+             event_id, entity_id, source_revision, authorization_revision,
+             search_generation, operation, created_at
+           ) VALUES (?, ?, ?, ?, ?, ?, ?)`)
+            .bind(context.eventId, entity.id, entity.lastrevid, authorizationRevision, searchGeneration, lifecycle.deletedAt ? 'delete' : 'upsert', context.createdAt));
+        return statements;
+    }
     #preparePatch(patch) {
         try {
             return prepareQuadPatch(this.#db, patch);
@@ -1037,13 +1520,24 @@ export class TaprootRepository {
         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
             .bind(entity.id, entity.lastrevid, json, metadata.actor ?? context.attribution?.id ?? null, context.attribution ? JSON.stringify(context.attribution) : null, metadata.editSummary ?? null, JSON.stringify(context.tags), context.eventId, context.contentHash, context.parentHash, context.lifecycle.deletedAt, context.lifecycle.redirectTo, context.createdAt);
     }
-    #auditInsert(entity, metadata, context) {
+    #auditInsert(entity, metadata, context, authorization) {
         return this.#db
             .prepare(`INSERT INTO taproot_audit_events(
           event_id, entity_id, revision, event_type, attribution_json, edit_summary,
           tags_json, request_id, content_hash, parent_hash, details_json, created_at
         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-            .bind(context.eventId, entity.id, entity.lastrevid, context.eventType, context.attribution ? JSON.stringify(context.attribution) : null, metadata.editSummary ?? null, JSON.stringify(context.tags), metadata.requestId ?? null, context.contentHash, context.parentHash, JSON.stringify(context.lifecycle), context.createdAt);
+            .bind(context.eventId, entity.id, entity.lastrevid, context.eventType, context.attribution ? JSON.stringify(context.attribution) : null, metadata.editSummary ?? null, JSON.stringify(context.tags), metadata.requestId ?? null, context.contentHash, context.parentHash, JSON.stringify({
+            ...context.lifecycle,
+            ...(authorization
+                ? {
+                    authorization: {
+                        action: authorization.action,
+                        authorizationRevision: authorization.authorizationRevision,
+                        searchGeneration: authorization.searchGeneration,
+                    },
+                }
+                : {}),
+        }), context.createdAt);
     }
     async #writeContext(entity, json, metadata, parentHash, eventType, lifecycle) {
         const attribution = normalizeAttribution(metadata);
@@ -1227,6 +1721,26 @@ function locateStatement(entity, id) {
     }
     throw new InvalidStatementError(`Statement ${id} does not exist`);
 }
+function resupplyStatementTexts(entity, supplied) {
+    const expected = new Set();
+    for (const statements of Object.values(entity.claims)) {
+        for (const statement of statements) {
+            expected.add(statement.id);
+            if (!Object.hasOwn(supplied, statement.id))
+                throw new InvalidStatementError(`Statement ${statement.id} text must be explicitly resupplied for this revision`);
+            const text = supplied[statement.id];
+            assertAuthoredStatementText(text, statement.id);
+            statement.text = text;
+        }
+    }
+    const unexpected = Object.keys(supplied).filter((id) => !expected.has(id));
+    if (unexpected.length)
+        throw new InvalidStatementError(`Statement text was supplied for unknown statement ${unexpected[0]}`);
+    return entity;
+}
+function authoredStatementTexts(entity) {
+    return Object.fromEntries(Object.values(entity.claims).flatMap((statements) => statements.map((statement) => [statement.id, statement.text])));
+}
 function collectSnak(snak, used) {
     const current = used.get(snak.property);
     if (current && current !== snak.datatype)
@@ -1234,6 +1748,15 @@ function collectSnak(snak, used) {
     used.set(snak.property, snak.datatype);
 }
 function applyEntityCommand(entity, command) {
+    if (command.type === 'add-statement' || command.type === 'replace-statement')
+        assertAuthoredStatementText(command.statement.text, command.statement.id);
+    else if (command.type === 'set-statement-rank' ||
+        command.type === 'add-qualifier' ||
+        command.type === 'remove-qualifier' ||
+        command.type === 'add-reference' ||
+        command.type === 'replace-reference' ||
+        command.type === 'remove-reference')
+        assertAuthoredStatementText(command.text, command.statementId);
     switch (command.type) {
         case 'set-label':
             entity.labels[command.language] = {
@@ -1302,10 +1825,13 @@ function applyEntityCommand(entity, command) {
         case 'set-statement-rank':
             locateStatement(entity, command.statementId).statement.rank =
                 command.rank;
+            locateStatement(entity, command.statementId).statement.text =
+                command.text;
             break;
         case 'add-qualifier': {
             validateSnak(command.snak);
             const statement = locateStatement(entity, command.statementId).statement;
+            statement.text = command.text;
             const property = command.snak.property;
             if (!statement.qualifiers[property]) {
                 statement.qualifiers[property] = [];
@@ -1316,6 +1842,7 @@ function applyEntityCommand(entity, command) {
         }
         case 'remove-qualifier': {
             const statement = locateStatement(entity, command.statementId).statement;
+            statement.text = command.text;
             const snaks = statement.qualifiers[command.property];
             if (!snaks?.[command.ordinal])
                 throw new InvalidStatementError('Qualifier does not exist');
@@ -1326,12 +1853,16 @@ function applyEntityCommand(entity, command) {
             }
             break;
         }
-        case 'add-reference':
-            locateStatement(entity, command.statementId).statement.references.push(structuredClone(command.reference));
+        case 'add-reference': {
+            const statement = locateStatement(entity, command.statementId).statement;
+            statement.text = command.text;
+            statement.references.push(structuredClone(command.reference));
             break;
+        }
         case 'replace-reference': {
-            const references = locateStatement(entity, command.statementId).statement
-                .references;
+            const statement = locateStatement(entity, command.statementId).statement;
+            statement.text = command.text;
+            const references = statement.references;
             const index = references.findIndex(({ hash }) => hash === command.hash);
             if (index < 0)
                 throw new InvalidStatementError(`Reference ${command.hash} does not exist`);
@@ -1339,8 +1870,9 @@ function applyEntityCommand(entity, command) {
             break;
         }
         case 'remove-reference': {
-            const references = locateStatement(entity, command.statementId).statement
-                .references;
+            const statement = locateStatement(entity, command.statementId).statement;
+            statement.text = command.text;
+            const references = statement.references;
             const index = references.findIndex(({ hash }) => hash === command.hash);
             if (index < 0)
                 throw new InvalidStatementError(`Reference ${command.hash} does not exist`);
@@ -1365,10 +1897,10 @@ function isUniqueEntityError(cause) {
     return /UNIQUE constraint failed: taproot_entities\.entity_id/iu.test(cause.message);
 }
 function isRevisionUniqueError(cause) {
-    return /UNIQUE constraint failed: taproot_entity_revisions\.entity_id, taproot_entity_revisions\.revision/iu.test(cause.message);
+    return (/UNIQUE constraint failed: taproot_entity_revisions\.entity_id, taproot_entity_revisions\.revision/iu.test(cause.message) || /taproot revisions cannot be replaced/iu.test(cause.message));
 }
 function isEventIdUniqueError(cause) {
-    return /UNIQUE constraint failed: taproot_audit_events\.event_id/iu.test(cause.message);
+    return (/UNIQUE constraint failed: taproot_audit_events\.event_id/iu.test(cause.message) || /taproot audit events cannot be replaced/iu.test(cause.message));
 }
 function normalizeAttribution(metadata) {
     if (metadata.actor !== undefined && typeof metadata.actor !== 'string')
@@ -1481,6 +2013,19 @@ function sameQuads(left, right) {
     const b = [...new Set(right.map(quadKeyValue))].sort();
     return JSON.stringify(a) === JSON.stringify(b);
 }
+function statementIds(entity) {
+    return Object.values(entity.claims)
+        .flatMap((statements) => statements.map(({ id }) => id))
+        .sort(compareCodeUnits);
+}
+function assertScopeDoesNotWiden(next, previous, field) {
+    const intersection = serializeVisibilityScope(intersectVisibilityScopes(next, previous));
+    if (intersection !== serializeVisibilityScope(next))
+        throw new InvalidEntityError(`${field} cannot widen canonical policy`);
+}
+function compareCodeUnits(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
 function toError(error) {
     return error instanceof Error ? error : new Error(String(error));
 }