@feltdb/core 0.11.7 → 0.11.9

package/dist/composition.js

@@ -0,0 +1,1218 @@
+import { FeltDBErrorCode, FeltDBServiceError } from './error-codes.js';
+import { AtomicTransactionError, conditionalRefusal } from './transaction.js';
+import { FELTDB_INTENT_COLLECTION, FELTDB_INTENT_EVENT_COLLECTION } from './intent.js';
+import { FELTDB_PROPOSAL_EVENT_COLLECTION, PROPOSAL_TRANSITIONS } from './proposal.js';
+import { FELTDB_COMPOSITION_COLLECTION, FELTDB_COMPOSITION_CONTRACT_COLLECTION, FELTDB_COMPOSITION_TOPOLOGY_COLLECTION, FELTDB_COMPOSITION_VERSION_COLLECTION, FELTDB_STATE_ATTRIBUTION_COLLECTION, FELTDB_STATE_CHANGE_COLLECTION, FELTDB_STATE_DEPENDENCY_COLLECTION, FELTDB_STATE_IMPACT_COLLECTION, FELTDB_STATE_OBSERVATION_COLLECTION, FELTDB_STATE_OWNERSHIP_COLLECTION, FELTDB_STATE_PROPOSAL_COLLECTION, canonicalDigest, changedFields, computeImpactSurface, consumerUri, emptyImpactReads, impactReadSet, impactSurfaceDigest, parseStateUri, recordValue, recordVersion, redactImpactSurface, stateUri, } from './state-impact.js';
+export * from './state-impact.js';
+export const COMPOSITION_CONTRACT_VERSION = 1;
+export const COMPOSITION_MAX_LIMIT = 1_000;
+/** Substrate capabilities, checked through the authorization gate. */
+export const COMPOSITION_CAPABILITIES = {
+    /** Record or re-record the authoritative contract identity. */
+    bind: 'composition:bind',
+    /** Admit a consumer's composition declaration. */
+    declare: 'composition:declare',
+    /** Act as a declared consumer. */
+    act: 'composition:act',
+    /** Approve or reject a state proposal. */
+    review: 'composition:review',
+};
+/** Every operation a consumer may be authorized for on one collection. */
+export const COMPOSITION_OPERATIONS = ['read', 'observe', 'write', 'delete'];
+/**
+ * The state-proposal operations, as a transport would expose them.
+ *
+ * This is the programmatic contract a service layer maps to its routes: one
+ * operation, one call, JSON in and JSON out. The subject is always the
+ * authenticated caller bound to the handle — never a request field — and the
+ * gate is always the deployment's authorization boundary.
+ */
+export const STATE_PROPOSAL_OPERATIONS = [
+    { operation: 'intend', on: 'consumer', method: 'intend', authorization: ['composition:act', 'read on every proposed record'],
+        writes: [FELTDB_INTENT_COLLECTION, FELTDB_INTENT_EVENT_COLLECTION, FELTDB_STATE_PROPOSAL_COLLECTION, FELTDB_STATE_IMPACT_COLLECTION, FELTDB_PROPOSAL_EVENT_COLLECTION] },
+    { operation: 'preview', on: 'consumer', method: 'preview', authorization: ['composition:act', 'read on every proposed record'], writes: [] },
+    { operation: 'history', on: 'consumer', method: 'history', authorization: ['composition:act', 'read on every proposed record'], writes: [] },
+    { operation: 'inspect', on: 'review', method: 'inspect', authorization: ['composition:review'], writes: [] },
+    { operation: 'approve', on: 'review', method: 'approve', authorization: ['composition:review'], writes: [FELTDB_STATE_PROPOSAL_COLLECTION, FELTDB_PROPOSAL_EVENT_COLLECTION] },
+    { operation: 'reject', on: 'review', method: 'reject', authorization: ['composition:review'], writes: [FELTDB_STATE_PROPOSAL_COLLECTION, FELTDB_PROPOSAL_EVENT_COLLECTION] },
+    { operation: 'rebase', on: 'consumer', method: 'rebase', authorization: ['composition:act', 'read on every proposed record'],
+        writes: [FELTDB_STATE_PROPOSAL_COLLECTION, FELTDB_STATE_IMPACT_COLLECTION, FELTDB_PROPOSAL_EVENT_COLLECTION, FELTDB_INTENT_COLLECTION, FELTDB_INTENT_EVENT_COLLECTION] },
+    { operation: 'apply', on: 'consumer', method: 'apply', authorization: ['composition:act', 'write (or delete, as owner) on every proposed record'],
+        writes: ['contract collections', FELTDB_STATE_CHANGE_COLLECTION, FELTDB_STATE_ATTRIBUTION_COLLECTION, FELTDB_STATE_PROPOSAL_COLLECTION, FELTDB_PROPOSAL_EVENT_COLLECTION, FELTDB_INTENT_COLLECTION, FELTDB_INTENT_EVENT_COLLECTION] },
+];
+// ─── contract identity ──────────────────────────────────────────────────────
+/** Identity of a compiled contract. The digest is the contract's own hash, not a new one. */
+export function contractIdentity(contract) {
+    const manifest = contract.manifest;
+    return {
+        contract_id: contract.application_id,
+        contract_digest: contract.hashes.application,
+        model_digest: contract.hashes.model,
+        collections: manifest.collections.map(value => value.name).sort(),
+        capabilities: manifest.capabilities.map(value => value.name).sort(),
+        fields: Object.fromEntries(manifest.collections.map(collection => [collection.name, collection.fields.map(field => ({
+                name: field.name, type: field.type, ...(field.reference ? { reference: field.reference } : {}),
+            }))])),
+        workflows: manifest.workflows.map(value => ({
+            name: value.name,
+            capabilities: [...new Set(value.steps.map(step => step.capability).filter((name) => Boolean(name)))].sort(),
+        })),
+        triggers: manifest.triggers.map(value => ({ name: value.name, event: value.event, workflow: value.workflow })),
+    };
+}
+const fail = (message, code = FeltDBErrorCode.VALIDATION_ERROR) => new FeltDBServiceError(message, code);
+const forbidden = (message) => fail(message, FeltDBErrorCode.FORBIDDEN);
+function identity(value, label) {
+    if (typeof value !== 'string' || !value.trim())
+        throw fail(`${label} must be a non-empty string`);
+    if (/[\s/:]/.test(value) || value.length > 200)
+        throw fail(`${label} must not contain whitespace, "/", or ":" and must be at most 200 characters`);
+    return value;
+}
+function text(value, label, max = 4_000) {
+    if (typeof value !== 'string' || !value.trim())
+        throw fail(`${label} must be a non-empty string`);
+    if (value.length > max)
+        throw fail(`${label} must be at most ${max} characters`);
+    return value.trim();
+}
+const EVIDENCE = /^[a-z][a-z0-9+.-]*:.+$/;
+function evidenceList(value, label) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw fail(`${label} must be an array of "scheme:reference" evidence references`);
+    return [...new Set(value.map((entry, index) => {
+            const reference = text(entry, `${label}[${index}]`, 1_000);
+            if (!EVIDENCE.test(reference))
+                throw fail(`${label}[${index}] "${reference}" must be a "scheme:reference" evidence reference`);
+            return reference;
+        }))].sort();
+}
+function closed(input, allowed, label) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw fail(`${label} must be an object`);
+    const extra = Object.keys(input).filter(key => !allowed.includes(key));
+    if (extra.length) {
+        throw fail(`${label} does not accept ${extra.join(', ')}. FeltDB records what happened; what it means belongs to the consumer.`);
+    }
+    return input;
+}
+function limit(value, fallback = 100) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value) || value < 1 || value > COMPOSITION_MAX_LIMIT) {
+        throw fail(`limit must be an integer between 1 and ${COMPOSITION_MAX_LIMIT}`, FeltDBErrorCode.QUERY_LIMIT_EXCEEDED);
+    }
+    return value;
+}
+function strip(row) {
+    const { id: _id, __version: _version, ...rest } = row ?? {};
+    return rest;
+}
+const page = (result, map) => ({
+    items: result.records.map(map),
+    ...(result.nextCursor ? { nextCursor: result.nextCursor } : {}),
+    exhausted: result.exhausted,
+});
+// ─── the service ────────────────────────────────────────────────────────────
+/**
+ * Bind to the authoritative contract and return a composition handle.
+ *
+ * The first bind records the contract identity. A later bind with a different
+ * digest is refused unless `rebind` is explicit and authorized, so an
+ * application holding an old contract cannot quietly redefine the authority.
+ */
+export async function openAuthoritativeComposition(db, options) {
+    if (!options?.authorization || typeof options.authorization.check !== 'function') {
+        throw forbidden('Authoritative composition requires an authorization gate; it fails closed without one');
+    }
+    const composition = new AuthoritativeComposition(db, options);
+    await composition.bind(options.rebind === true);
+    return composition;
+}
+export class AuthoritativeComposition {
+    db;
+    contract;
+    tenantId;
+    subject;
+    environment;
+    gate;
+    source;
+    clock;
+    flowHash;
+    constructor(db, options) {
+        this.db = db;
+        this.contract = contractIdentity(options.contract);
+        identity(this.contract.contract_id, 'contract id');
+        this.tenantId = identity(options.tenantId, 'tenantId');
+        if (!options.subject?.kind || !options.subject?.id)
+            throw fail('subject requires a kind and an id');
+        this.subject = { kind: options.subject.kind, id: text(options.subject.id, 'subject.id', 200) };
+        this.source = text(options.source, 'source', 200);
+        this.environment = options.environment ?? 'production';
+        this.gate = options.authorization;
+        this.clock = options.now ?? (() => new Date());
+        this.flowHash = options.contract.hashes.model;
+    }
+    /**
+     * @internal Durable record key for a tenant- and contract-scoped identity.
+     * Record ids are restricted to `[A-Za-z0-9._-]`, so the scoped identity is
+     * digested; the readable identity lives in the row itself.
+     */
+    async key(...parts) {
+        return `k.${(await canonicalDigest([this.tenantId, this.contract.contract_id, ...parts])).slice(7, 47)}`;
+    }
+    resource(collection, record = '*') {
+        return stateUri({ contract: this.contract.contract_id, collection, record });
+    }
+    now() { return this.clock().toISOString(); }
+    /** @internal Ask the gate; fail closed. Returns the decision id. */
+    async authorize(capability, uri, operation, consumer) {
+        let decision;
+        try {
+            decision = await this.gate.check({
+                subject: this.subject,
+                tenant_id: this.tenantId,
+                application_id: this.contract.contract_id,
+                resource: { uri, attributes: { operation, ...(consumer ? { consumer } : {}) } },
+                capability,
+                context: { timestamp: this.clock().getTime(), attributes: { operation } },
+            });
+        }
+        catch (error) {
+            throw forbidden(`${capability} could not be authorized for ${uri}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (decision?.allowed !== true) {
+            throw forbidden(`${capability} (${operation}) was not allowed for ${this.subject.kind}:${this.subject.id} on ${uri}${decision?.reason ? `: ${decision.reason}` : ''}`);
+        }
+        return decision.decision_id;
+    }
+    /** @internal Non-throwing form, for reporting what a reader may do. */
+    async allowed(capability, uri, operation, consumer) {
+        try {
+            await this.authorize(capability, uri, operation, consumer);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** @internal */
+    provenance(decisionIds) {
+        return {
+            subject: this.subject, tenant_id: this.tenantId, contract_id: this.contract.contract_id,
+            source: this.source, recorded_at: this.now(), authorization_decision_ids: [...new Set(decisionIds)],
+        };
+    }
+    /** @internal */
+    async bind(rebind) {
+        const key = await this.key();
+        const row = await this.db.collection(FELTDB_COMPOSITION_CONTRACT_COLLECTION).get(key);
+        if (row && row.contract_digest === this.contract.contract_digest)
+            return;
+        if (row && !rebind) {
+            throw fail(`The authoritative contract ${this.contract.contract_id} is bound at ${String(row.contract_digest)}, `
+                + `not ${this.contract.contract_digest}. Rebind explicitly to change the authority.`, FeltDBErrorCode.CONTRACT_UNSUPPORTED);
+        }
+        const decision = await this.authorize(COMPOSITION_CAPABILITIES.bind, this.resource(FELTDB_COMPOSITION_CONTRACT_COLLECTION, this.contract.contract_id), 'bind');
+        const value = {
+            tenant_id: this.tenantId, contract_id: this.contract.contract_id, contract_digest: this.contract.contract_digest,
+            model_digest: this.contract.model_digest, collections: this.contract.collections, capabilities: this.contract.capabilities,
+            previous_digests: row ? [...(row.previous_digests ?? []), row.contract_digest] : [],
+            contract_version: COMPOSITION_CONTRACT_VERSION, provenance: this.provenance([decision]),
+        };
+        await this.db.transaction(tx => {
+            tx.collection(FELTDB_COMPOSITION_CONTRACT_COLLECTION).set(key, value, row ? { ifVersion: recordVersion(row) } : { requireAbsent: true });
+        });
+    }
+    /** @internal Key of a record's attribution head. */
+    attributionKey(collection, id) {
+        return this.key('attribution', collection, id);
+    }
+    /** @internal Stage a topology-head advance; every declaration and connection fences on it. */
+    async stageTopology(tx) {
+        const key = await this.key();
+        const head = await this.db.collection(FELTDB_COMPOSITION_TOPOLOGY_COLLECTION).get(key);
+        tx.collection(FELTDB_COMPOSITION_TOPOLOGY_COLLECTION).set(key, {
+            tenant_id: this.tenantId, contract_id: this.contract.contract_id, advanced_at: this.now(),
+        }, head ? { ifVersion: recordVersion(head) } : { requireAbsent: true });
+    }
+    // ── declarations ──
+    normalizeDeclaration(input) {
+        closed(input, ['consumer', 'access', 'projections'], 'composition declaration');
+        const consumer = identity(input.consumer, 'consumer');
+        if (!Array.isArray(input.access) || input.access.length === 0)
+            throw fail('access must declare at least one collection');
+        const collections = new Set();
+        const access = input.access.map((entry, index) => {
+            closed(entry, ['collection', 'mode', 'capability'], `access[${index}]`);
+            const collection = text(entry.collection, `access[${index}].collection`, 200);
+            if (!this.contract.collections.includes(collection))
+                throw fail(`access[${index}].collection ${collection} is not a collection of contract ${this.contract.contract_id}`);
+            if (collections.has(collection))
+                throw fail(`access declares ${collection} more than once`);
+            collections.add(collection);
+            if (!['observe', 'mutate', 'own'].includes(entry.mode))
+                throw fail(`access[${index}].mode must be observe, mutate, or own`);
+            const capability = text(entry.capability, `access[${index}].capability`, 200);
+            if (!this.contract.capabilities.includes(capability))
+                throw fail(`access[${index}].capability ${capability} is not declared by the contract`);
+            return { collection, mode: entry.mode, capability };
+        }).sort((a, b) => a.collection.localeCompare(b.collection));
+        const names = new Set();
+        const projections = (input.projections ?? []).map((projection, index) => {
+            closed(projection, ['name', 'sources'], `projections[${index}]`);
+            const name = identity(projection.name, `projections[${index}].name`);
+            if (names.has(name))
+                throw fail(`projection ${name} is declared twice`);
+            if (this.contract.collections.includes(name)) {
+                throw fail(`projection ${name} has the name of an authoritative collection; a projection can never stand in for authority`);
+            }
+            names.add(name);
+            if (!Array.isArray(projection.sources) || projection.sources.length === 0)
+                throw fail(`projection ${name} must name its sources`);
+            for (const source of projection.sources) {
+                if (!collections.has(source))
+                    throw fail(`projection ${name} derives from ${source}, which this consumer has not declared access to`);
+            }
+            return { name, sources: [...new Set(projection.sources)].sort() };
+        }).sort((a, b) => a.name.localeCompare(b.name));
+        return { consumer, access, projections };
+    }
+    compositions = {
+        /**
+         * Admit a consumer's composition, or a new version of it.
+         *
+         * Declaration, version history, exclusive ownership claims, and the
+         * topology head commit in one transaction. Ownership is exclusive: a
+         * collection owned by another consumer refuses the whole declaration.
+         */
+        declare: async (input) => {
+            const declaration = this.normalizeDeclaration(input);
+            const consumer = declaration.consumer;
+            const decision = await this.authorize(COMPOSITION_CAPABILITIES.declare, consumerUri(this.contract.contract_id, consumer), 'declare', consumer);
+            const headKey = await this.key(consumer);
+            const head = await this.db.collection(FELTDB_COMPOSITION_COLLECTION).get(headKey);
+            const previous = head ? strip(head) : undefined;
+            const owned = new Set(declaration.access.filter(value => value.mode === 'own').map(value => value.collection));
+            const previouslyOwned = new Set((previous?.access ?? []).filter(value => value.mode === 'own').map(value => value.collection));
+            const claims = new Map();
+            for (const collection of new Set([...owned, ...previouslyOwned])) {
+                const claim = await this.db.collection(FELTDB_STATE_OWNERSHIP_COLLECTION).get(await this.key(collection));
+                if (claim && claim.owner !== consumer && owned.has(collection)) {
+                    throw fail(`${collection} is owned by ${String(claim.owner)}; ownership is exclusive`, FeltDBErrorCode.CONFLICT);
+                }
+                claims.set(collection, claim);
+            }
+            const version = (previous?.version ?? 0) + 1;
+            const digest = await canonicalDigest({ contract: this.contract.contract_digest, ...declaration });
+            if (previous && previous.digest === digest)
+                return previous;
+            const composition = {
+                consumer, uri: consumerUri(this.contract.contract_id, consumer), tenant_id: this.tenantId,
+                contract_id: this.contract.contract_id, contract_digest: this.contract.contract_digest,
+                version, digest, status: 'active', access: declaration.access, projections: declaration.projections,
+                requires: [...new Set(declaration.access.map(value => value.capability))].sort(),
+                declared_at: this.now(), provenance: this.provenance([decision]),
+            };
+            const versionKey = await this.key(consumer, String(version));
+            const claimKeys = new Map(await Promise.all([...claims.keys()].map(async (collection) => [collection, await this.key(collection)])));
+            await this.db.transaction(async (tx) => {
+                tx.collection(FELTDB_COMPOSITION_COLLECTION).set(headKey, composition, head ? { ifVersion: recordVersion(head) } : { requireAbsent: true });
+                tx.collection(FELTDB_COMPOSITION_VERSION_COLLECTION).set(versionKey, composition, { requireAbsent: true });
+                for (const [collection, claim] of claims) {
+                    const claimKey = claimKeys.get(collection);
+                    if (owned.has(collection) && !claim) {
+                        tx.collection(FELTDB_STATE_OWNERSHIP_COLLECTION).set(claimKey, {
+                            tenant_id: this.tenantId, contract_id: this.contract.contract_id, collection, owner: consumer, claimed_at: this.now(),
+                        }, { requireAbsent: true });
+                    }
+                    else if (!owned.has(collection) && claim?.owner === consumer) {
+                        tx.collection(FELTDB_STATE_OWNERSHIP_COLLECTION).delete(claimKey, { ifVersion: recordVersion(claim) });
+                    }
+                }
+                await this.stageTopology(tx);
+            });
+            return composition;
+        },
+        get: async (consumer) => {
+            const row = await this.db.collection(FELTDB_COMPOSITION_COLLECTION).get(await this.key(identity(consumer, 'consumer')));
+            if (!row)
+                throw fail(`No composition is declared for ${consumer}`, FeltDBErrorCode.NOT_FOUND);
+            return strip(row);
+        },
+        /** Page declared compositions over this contract. */
+        list: async (input = {}) => page(await this.db.query({
+            collection: FELTDB_COMPOSITION_COLLECTION,
+            where: [{ field: 'tenant_id', eq: this.tenantId }, { field: 'contract_id', eq: this.contract.contract_id }],
+            orderBy: [{ field: 'consumer', direction: 'asc' }],
+            limit: limit(input.limit), ...(input.cursor ? { cursor: input.cursor } : {}),
+        }), row => strip(row)),
+    };
+    /** Act as a declared consumer. The subject must be authorized to act as it. */
+    async consumer(consumer) {
+        const id = identity(consumer, 'consumer');
+        await this.authorize(COMPOSITION_CAPABILITIES.act, consumerUri(this.contract.contract_id, id), 'act', id);
+        const composition = await this.compositions.get(id);
+        if (composition.contract_digest !== this.contract.contract_digest) {
+            throw fail(`${id} was admitted against contract ${composition.contract_digest}; the authority is ${this.contract.contract_digest}. Redeclare it.`, FeltDBErrorCode.CONTRACT_UNSUPPORTED);
+        }
+        return new CompositionConsumer(this, this.db, composition);
+    }
+    // ── the basis snapshot ──
+    /**
+     * @internal The runtime snapshot impact is computed from: every contract
+     * collection plus this contract's composition, dependency, attribution, and
+     * topology records. A control-plane materialization, never a request path.
+     */
+    async basis() {
+        const scope = [{ field: 'tenant_id', eq: this.tenantId }, { field: 'contract_id', eq: this.contract.contract_id }];
+        const sources = [
+            ...this.contract.collections.map(collection => ({ collection })),
+            ...[FELTDB_COMPOSITION_COLLECTION, FELTDB_STATE_DEPENDENCY_COLLECTION, FELTDB_STATE_ATTRIBUTION_COLLECTION, FELTDB_COMPOSITION_TOPOLOGY_COLLECTION, FELTDB_COMPOSITION_CONTRACT_COLLECTION]
+                .map(collection => ({ collection, where: scope })),
+        ];
+        const handle = this.db.snapshot({ name: `composition/${this.tenantId}/${this.contract.contract_id}/basis/v2`, sources });
+        let snapshot = await handle.refresh();
+        // A runtime without revisions cannot prove a materialization did not span
+        // a write. Two consecutive builds with the same content identity did not
+        // straddle a completed write to anything they read; that is the basis.
+        for (let attempt = 0; snapshot.basis.coherence !== 'proven'; attempt++) {
+            if (attempt === 3) {
+                throw fail('Could not materialize a stable basis snapshot; authoritative state kept changing', FeltDBErrorCode.VERSION_CONFLICT);
+            }
+            const again = await handle.refresh({ force: true });
+            if (again.identity.id === snapshot.identity.id)
+                break;
+            snapshot = again;
+        }
+        const topology = snapshot.get(FELTDB_COMPOSITION_TOPOLOGY_COLLECTION, await this.key());
+        return {
+            snapshot,
+            binding: {
+                id: snapshot.identity.id, version: snapshot.identity.version,
+                ...(snapshot.identity.scope ? { scope: snapshot.identity.scope } : {}),
+                coherence: snapshot.basis.coherence, derivation: snapshot.identity.derivation,
+                topology_version: recordVersion(topology),
+            },
+        };
+    }
+    /** @internal */
+    impactOf(snapshot, operations) {
+        return computeImpactSurface({ contract: this.contract, tenantId: this.tenantId, basis: snapshot, operations });
+    }
+    /**
+     * @internal The impact of `operations` against a basis snapshot, together
+     * with the authority's read basis for exactly the state that impact read.
+     *
+     * The read basis is captured between two materializations of the basis
+     * snapshot; equal snapshot identities prove no write reached the snapshot's
+     * sources in between, so the basis describes the state the impact was
+     * computed from — not some later state.
+     */
+    async anchoredImpact(operations) {
+        for (let attempt = 0; attempt < 3; attempt++) {
+            const { snapshot, binding } = await this.basis();
+            const reads = emptyImpactReads();
+            const surface = await computeImpactSurface({ contract: this.contract, tenantId: this.tenantId, basis: snapshot, operations, reads });
+            const scopeKey = await this.key();
+            reads.records.set('binding', { collection: FELTDB_COMPOSITION_CONTRACT_COLLECTION, id: scopeKey });
+            const readBasis = await this.db.readBasis(impactReadSet(reads));
+            const after = await this.basis();
+            if (after.binding.id === binding.id)
+                return { snapshot, binding, surface, readBasis };
+        }
+        throw fail('Authoritative state kept changing while the impact basis was being established; retry', FeltDBErrorCode.VERSION_CONFLICT);
+    }
+    /** @internal Proposal and impact ids are generated, globally unique, and key-safe. */
+    proposalKey(proposalId) { return proposalId; }
+    /** @internal */
+    async readProposal(proposalId) {
+        const row = await this.db.collection(FELTDB_STATE_PROPOSAL_COLLECTION).get(identity(proposalId, 'proposalId'));
+        if (!row || row.tenant_id !== this.tenantId || row.contract_id !== this.contract.contract_id) {
+            throw fail(`State proposal ${proposalId} was not found`, FeltDBErrorCode.NOT_FOUND);
+        }
+        const proposal = strip(row);
+        const impactRow = await this.db.collection(FELTDB_STATE_IMPACT_COLLECTION).get(proposal.impact_id);
+        // Written in the same transaction as the proposal. Its absence is corruption, not a missing optional.
+        if (!impactRow)
+            throw fail(`State proposal ${proposalId} has no impact record ${proposal.impact_id}`, FeltDBErrorCode.RECOVERY_FAILURE);
+        return { proposal, row, impact: strip(impactRow) };
+    }
+    /**
+     * Is the recorded impact still a description of current authoritative state?
+     *
+     * The direct records are compared by version and digest, and the surface is
+     * re-derived from a current snapshot and compared by digest. Unrelated
+     * writes advance the basis without blocking; anything the surface depends on
+     * blocks.
+     *
+     * @internal Unauthorized by itself; readers get it through `preview()` and
+     * reviewers through `review.inspect()`.
+     */
+    async readiness(proposalId) {
+        return (await this.assess(proposalId)).readiness;
+    }
+    /**
+     * @internal Readiness, re-derived for explanation, and checked against the
+     * proposal's persisted read basis.
+     *
+     * The re-derived surface says *what* differs; the read basis says *whether*
+     * anything the approved impact was computed from has changed, by asking the
+     * authority for its token over the same reads now. `apply` enforces the same
+     * basis inside the commit, so readiness and apply cannot disagree about a
+     * change that happened before the check.
+     */
+    async assess(proposalId) {
+        const { proposal, row, impact } = await this.readProposal(proposalId);
+        const current = await this.basis();
+        const blockers = new Set();
+        const changed = [];
+        for (const operation of proposal.operations) {
+            const record = current.snapshot.get(operation.collection, operation.record_id);
+            const value = recordValue(record);
+            const digest = value === null ? null : await canonicalDigest(value);
+            if (recordVersion(record) !== operation.base_version || digest !== operation.base_value_digest)
+                changed.push(operation.subject);
+        }
+        if (changed.length)
+            blockers.add('direct_state_changed');
+        if (proposal.contract_digest !== this.contract.contract_digest)
+            blockers.add('contract_changed');
+        const surface = await this.impactOf(current.snapshot, toOperations(proposal));
+        const digest = await impactSurfaceDigest(surface);
+        if (digest !== impact.surface_digest)
+            blockers.add('impact_changed');
+        if (!impact.read_basis)
+            blockers.add('basis_changed');
+        else if ((await this.db.readBasis(impact.read_basis.reads)).token !== impact.read_basis.token)
+            blockers.add('basis_changed');
+        if (!['previewed', 'approved'].includes(proposal.status))
+            blockers.add('not_current_status');
+        const stale = [...blockers].some(value => value !== 'not_current_status');
+        return {
+            proposal, row, impact,
+            readiness: {
+                proposal_id: proposal.proposal_id, status: proposal.status,
+                readiness: blockers.size ? 'blocked' : 'ready', blockers: [...blockers].sort(), stale,
+                base_snapshot: proposal.base_snapshot, current_snapshot: current.binding,
+                basis_advanced: current.binding.id !== proposal.base_snapshot.id,
+                topology_advanced: current.binding.topology_version !== proposal.base_snapshot.topology_version,
+                changed_subjects: changed.sort(), current_impact_digest: digest,
+            },
+        };
+    }
+    /** @internal Stage one lifecycle move and its shared `_feltdb.ProposalEvent`. */
+    stageProposalMove(tx, proposal, row, to, actor, metadata = {}) {
+        if (row && !PROPOSAL_TRANSITIONS[proposal.status].includes(to)) {
+            throw fail(`INVALID_PROPOSAL_TRANSITION: ${proposal.status} -> ${to}`, FeltDBErrorCode.CONFLICT);
+        }
+        const from = row ? proposal.status : undefined;
+        const next = { ...proposal, status: to };
+        tx.collection(FELTDB_STATE_PROPOSAL_COLLECTION).set(proposal.proposal_id, next, row ? { ifVersion: recordVersion(row) } : { requireAbsent: true });
+        this.stageProposalEvent(tx, proposal.proposal_id, from, to, actor, metadata);
+        return next;
+    }
+    /** @internal */
+    stageProposalEvent(tx, proposalId, from, to, actor, metadata) {
+        const event = {
+            id: `pe_${crypto.randomUUID().replace(/-/g, '')}`, proposal_id: proposalId,
+            ...(from ? { from_status: from } : {}), to_status: to, actor, created_at: this.now(), metadata: { kind: 'state', ...metadata },
+        };
+        tx.collection(FELTDB_PROPOSAL_EVENT_COLLECTION).set(event.id, event, { requireAbsent: true });
+    }
+    /** @internal Stage an intent status move and its `_feltdb.IntentEvent`. */
+    stageIntent(tx, intent, row, status, metadata = {}) {
+        const next = { ...intent, status };
+        tx.collection(FELTDB_INTENT_COLLECTION).set(intent.id, next, row ? { ifVersion: recordVersion(row) } : { requireAbsent: true });
+        this.stageIntentEvent(tx, intent.id, status, metadata);
+        return next;
+    }
+    /** @internal */
+    stageIntentEvent(tx, intentId, status, metadata) {
+        const event = { id: `ie_${crypto.randomUUID().replace(/-/g, '')}`, intent_id: intentId, status, created_at: this.now(), metadata };
+        tx.collection(FELTDB_INTENT_EVENT_COLLECTION).set(event.id, event, { requireAbsent: true });
+    }
+    /** @internal */
+    intentFor(proposal, request, parent) {
+        return {
+            id: proposal.intent_id, application_id: this.contract.contract_id, environment: this.environment,
+            raw_request: request, action: 'transition', target: 'state',
+            ...(parent ? { parent_intent_id: parent } : {}),
+            contract_hash: this.contract.contract_digest, flow_hash: this.flowHash,
+            status: 'received', ambiguities: [], created_at: this.now(), proposal_id: proposal.proposal_id,
+        };
+    }
+    review = {
+        /**
+         * Approve a previewed proposal whose impact is still current.
+         *
+         * Approval binds to the exact impact record and digest. It grants nothing:
+         * `apply` still authorizes every write for the consumer that applies.
+         */
+        approve: async (proposalId, input = {}) => {
+            const { proposal, row, impact } = await this.readProposal(proposalId);
+            const decision = await this.authorize(COMPOSITION_CAPABILITIES.review, this.resource(FELTDB_STATE_PROPOSAL_COLLECTION, proposal.proposal_id), 'approve');
+            const readiness = await this.readiness(proposalId);
+            if (readiness.stale) {
+                throw fail(`State proposal ${proposalId} is stale (${readiness.blockers.join(', ')}); rebase it before review`, FeltDBErrorCode.VERSION_CONFLICT);
+            }
+            let result;
+            await this.db.transaction(tx => {
+                result = this.stageProposalMove(tx, {
+                    ...proposal,
+                    approval: {
+                        impact_id: impact.impact_id, impact_digest: impact.surface_digest, approved_by: this.subject,
+                        decision_id: decision, approved_at: this.now(), ...(input.note ? { note: text(input.note, 'note') } : {}),
+                    },
+                }, row, 'approved', `${this.subject.kind}:${this.subject.id}`, { impact_id: impact.impact_id });
+            });
+            return result;
+        },
+        reject: async (proposalId, reason) => {
+            const { proposal, row } = await this.readProposal(proposalId);
+            const decision = await this.authorize(COMPOSITION_CAPABILITIES.review, this.resource(FELTDB_STATE_PROPOSAL_COLLECTION, proposal.proposal_id), 'reject');
+            let result;
+            await this.db.transaction(tx => {
+                result = this.stageProposalMove(tx, {
+                    ...proposal, rejection: { rejected_by: this.subject, decision_id: decision, rejected_at: this.now(), reason: text(reason, 'reason') },
+                }, row, 'rejected', `${this.subject.kind}:${this.subject.id}`, { reason });
+            });
+            return result;
+        },
+        /** The full, unredacted proposal and impact, for an authorized reviewer. */
+        inspect: async (proposalId) => {
+            const { proposal, impact } = await this.readProposal(proposalId);
+            await this.authorize(COMPOSITION_CAPABILITIES.review, this.resource(FELTDB_STATE_PROPOSAL_COLLECTION, proposal.proposal_id), 'inspect');
+            return { proposal, impact, readiness: await this.readiness(proposalId) };
+        },
+    };
+}
+const LIFECYCLE_RANK = { proposed: 0, validated: 1, previewed: 2, approved: 3, applied: 4, rejected: 4, expired: 4 };
+function toOperations(proposal) {
+    return proposal.operations.map(value => value.operation === 'delete'
+        ? { collection: value.collection, id: value.record_id, delete: true }
+        : { collection: value.collection, id: value.record_id, value: value.value });
+}
+/**
+ * One application, service, or agent composing over the contract.
+ *
+ * Every operation checks the declaration (the ceiling) and then asks the gate
+ * (the authority). Reading does not imply writing, writing does not imply
+ * deleting, and referencing or observing implies neither.
+ */
+export class CompositionConsumer {
+    service;
+    db;
+    composition;
+    constructor(service, db, composition) {
+        this.service = service;
+        this.db = db;
+        this.composition = composition;
+    }
+    get id() { return this.composition.consumer; }
+    get contractId() { return this.service.contract.contract_id; }
+    ref(collection, record) { return { contract: this.contractId, collection, ...(record === undefined ? {} : { record }) }; }
+    /** Refuse to act on a declaration that has been superseded since this handle was opened. */
+    async current() {
+        const latest = await this.service.compositions.get(this.id);
+        if (latest.version !== this.composition.version) {
+            throw fail(`${this.id} is now at composition version ${latest.version}; reopen the consumer`, FeltDBErrorCode.VERSION_CONFLICT);
+        }
+    }
+    entry(collection) {
+        return this.composition.access.find(value => value.collection === collection);
+    }
+    /** Declaration ceiling, then the gate. Returns the capability and the decision id. */
+    async access(collection, operation, record) {
+        const entry = this.entry(collection);
+        if (!entry)
+            throw forbidden(`${this.id} has not declared access to ${collection}`);
+        if (operation === 'write' && entry.mode === 'observe')
+            throw forbidden(`${this.id} observes ${collection}; observing does not include mutation`);
+        if (operation === 'delete' && entry.mode !== 'own')
+            throw forbidden(`${this.id} does not own ${collection}; only its owner may delete`);
+        const decision = await this.service.authorize(entry.capability, stateUri(this.ref(collection, record ?? '*')), operation, this.id);
+        return { capability: entry.capability, decision };
+    }
+    /** What this consumer is authorized to do, per declared collection, evaluated now. */
+    async authorizedOperations() {
+        return Promise.all(this.composition.access.map(async (entry) => {
+            const operations = {};
+            for (const operation of COMPOSITION_OPERATIONS) {
+                const ceiling = operation === 'write' ? entry.mode !== 'observe' : operation === 'delete' ? entry.mode === 'own' : true;
+                operations[operation] = ceiling && await this.service.allowed(entry.capability, stateUri(this.ref(entry.collection, '*')), operation, this.id);
+            }
+            return { collection: entry.collection, uri: stateUri(this.ref(entry.collection)), mode: entry.mode, capability: entry.capability, operations };
+        }));
+    }
+    async readable(collection) {
+        const entry = this.entry(collection);
+        return Boolean(entry) && this.service.allowed(entry.capability, stateUri(this.ref(collection, '*')), 'read', this.id);
+    }
+    // ── authoritative state ──
+    async read(collection, id) {
+        await this.current();
+        await this.access(collection, 'read', id);
+        const row = await this.db.collection(collection).get(id);
+        const ref = this.ref(collection, id);
+        return { uri: stateUri(ref), ref, exists: Boolean(row), version: recordVersion(row), value: recordValue(row) };
+    }
+    async query(request) {
+        await this.current();
+        await this.access(request.collection, 'read');
+        return page(await this.db.query(request), row => {
+            const ref = this.ref(request.collection, String(row.id));
+            return { uri: stateUri(ref), ref, exists: true, version: recordVersion(row), value: recordValue(row) };
+        });
+    }
+    /**
+     * Stage attributed writes. A write to a collection this consumer only
+     * observes, or a delete of a collection it does not own, is refused before
+     * anything commits; so is anything the gate denies.
+     */
+    async mutate(build, options = {}) {
+        const writes = [];
+        build({
+            set: (collection, id, value) => { writes.push({ collection, id: String(id), value }); },
+            delete: (collection, id) => { writes.push({ collection, id: String(id) }); },
+        });
+        return this.commit(writes, { ...options });
+    }
+    async commit(writes, meta) {
+        await this.current();
+        if (!writes.length)
+            throw fail('a mutation requires at least one write');
+        const seen = new Set();
+        for (const write of writes) {
+            const key = `${write.collection}\u0000${write.id}`;
+            if (seen.has(key))
+                throw fail(`${write.collection}/${write.id} is written twice in one mutation`);
+            seen.add(key);
+            if (!this.service.contract.collections.includes(write.collection)) {
+                throw forbidden(`${write.collection} is not a collection of contract ${this.contractId}; the substrate writes nothing else as state`);
+            }
+        }
+        const transactionId = meta.transactionId ?? `ctx_${crypto.randomUUID().replace(/-/g, '')}`;
+        const recordedAt = this.service.now();
+        const planned = await Promise.all(writes.map(async (write, index) => {
+            const { capability, decision } = await this.access(write.collection, write.value === undefined ? 'delete' : 'write', write.id);
+            const row = await this.db.collection(write.collection).get(write.id);
+            const version = recordVersion(row);
+            if (write.expected && write.expected.version !== version) {
+                throw fail(`${write.collection}/${write.id} is at version ${version}, not ${write.expected.version}`, FeltDBErrorCode.VERSION_CONFLICT);
+            }
+            if (write.value === undefined && !row)
+                throw fail(`${write.collection}/${write.id} does not exist`, FeltDBErrorCode.NOT_FOUND);
+            const subject = stateUri(this.ref(write.collection, write.id));
+            const headKey = await this.service.attributionKey(write.collection, write.id);
+            const head = await this.db.collection(FELTDB_STATE_ATTRIBUTION_COLLECTION).get(headKey);
+            const before = recordValue(row);
+            const value = write.value === undefined ? null : recordValue(write.value);
+            const change = {
+                change_id: `${transactionId}.${index + 1}`,
+                tenant_id: this.service.tenantId, contract_id: this.contractId, contract_digest: this.service.contract.contract_digest,
+                subject, collection: write.collection, record_id: write.id,
+                operation: value === null ? 'delete' : row ? 'update' : 'insert',
+                version_before: version, version_after: value === null ? null : (version ?? 0) + 1,
+                value_digest_before: before === null ? null : await canonicalDigest(before),
+                value_digest_after: value === null ? null : await canonicalDigest(value),
+                fields_changed: changedFields(before, value),
+                attribution_version: (recordVersion(head) ?? 0) + 1,
+                transaction_id: transactionId, consumer: this.id, capability,
+                ...(meta.causalId ? { causal_id: text(meta.causalId, 'causalId', 200) } : {}),
+                ...(meta.proposal ? { intent_id: meta.proposal.intent_id, proposal_id: meta.proposal.proposal_id, impact_id: meta.proposal.impact_id } : {}),
+                recorded_at: recordedAt, provenance: this.service.provenance([decision]),
+            };
+            return { write, row, head, headKey, value, change };
+        }));
+        const changes = planned.map(value => value.change);
+        const transaction = await this.db.transaction(tx => {
+            for (const basis of meta.fences ?? [])
+                tx.fence(basis);
+            for (const { write, row, head, headKey, value, change } of planned) {
+                const guard = row ? { ifVersion: recordVersion(row) } : { requireAbsent: true };
+                if (value === null)
+                    tx.collection(write.collection).delete(write.id, guard);
+                else
+                    tx.collection(write.collection).set(write.id, value, guard);
+                tx.collection(FELTDB_STATE_CHANGE_COLLECTION).set(change.change_id, change, { requireAbsent: true });
+                tx.collection(FELTDB_STATE_ATTRIBUTION_COLLECTION).set(headKey, {
+                    tenant_id: this.service.tenantId, contract_id: this.contractId, subject: change.subject,
+                    collection: write.collection, record_id: write.id, last_change_id: change.change_id,
+                    record_version: change.version_after, transaction_id: transactionId,
+                }, head ? { ifVersion: recordVersion(head) } : { requireAbsent: true });
+            }
+            meta.stage?.(tx, changes, transactionId);
+        }, { transactionId });
+        return { transaction, changes };
+    }
+    /** Attributed changes to one collection (optionally one record), oldest first per record. */
+    async changes(input) {
+        await this.current();
+        await this.access(input.collection, 'observe', input.record);
+        return page(await this.db.query({
+            collection: FELTDB_STATE_CHANGE_COLLECTION,
+            where: [
+                { field: 'tenant_id', eq: this.service.tenantId }, { field: 'contract_id', eq: this.contractId },
+                { field: 'collection', eq: input.collection }, ...(input.record ? [{ field: 'record_id', eq: input.record }] : []),
+            ],
+            orderBy: input.record ? [{ field: 'attribution_version', direction: 'asc' }] : [{ field: 'recorded_at', direction: 'asc' }],
+            limit: limit(input.limit), ...(input.cursor ? { cursor: input.cursor } : {}),
+        }), row => strip(row));
+    }
+    async changeById(changeId) {
+        const row = await this.db.collection(FELTDB_STATE_CHANGE_COLLECTION).get(changeId);
+        if (!row || row.tenant_id !== this.service.tenantId || row.contract_id !== this.contractId)
+            throw fail(`Change ${changeId} was not found`, FeltDBErrorCode.NOT_FOUND);
+        return strip(row);
+    }
+    /**
+     * Record that this consumer observed a subject, optionally a specific change.
+     *
+     * The schema is closed: there is no field for what the observation means.
+     */
+    async observe(input) {
+        await this.current();
+        closed(input, ['subject', 'change', 'evidence', 'context', 'observedAt', 'observationId'], 'observation');
+        const subject = parseStateUri(text(input.subject, 'subject', 2_000));
+        if (subject.contract !== this.contractId)
+            throw fail(`${input.subject} belongs to another contract`);
+        const { decision } = await this.access(subject.collection, 'observe', subject.record);
+        const evidence = evidenceList(input.evidence, 'evidence');
+        if (input.change !== undefined) {
+            const change = await this.changeById(text(input.change, 'change', 400));
+            if (change.subject !== stateUri(subject))
+                throw fail(`change ${change.change_id} is not a change to ${input.subject}`);
+            evidence.push(`change:${change.change_id}`);
+        }
+        const context = input.context === undefined ? {} : closed(input.context, ['causal_id', 'parent_observation_id', 'correlation_id'], 'observation context');
+        const observationId = input.observationId === undefined ? `obs_${crypto.randomUUID().replace(/-/g, '')}` : identity(input.observationId, 'observationId');
+        const observation = {
+            observation_id: observationId, tenant_id: this.service.tenantId, contract_id: this.contractId,
+            subject: stateUri(subject), ...(input.change ? { change_id: input.change } : {}), consumer: this.id,
+            observed_at: input.observedAt ? new Date(input.observedAt).toISOString() : this.service.now(), recorded_at: this.service.now(),
+            evidence: [...new Set(evidence)].sort(),
+            context: Object.fromEntries(Object.entries(context).map(([key, value]) => [key, text(value, `context.${key}`, 400)])),
+            provenance: this.service.provenance([decision]),
+        };
+        await this.db.transaction(tx => {
+            tx.collection(FELTDB_STATE_OBSERVATION_COLLECTION).set(observationId, observation, { requireAbsent: true });
+        });
+        return observation;
+    }
+    async observations(input) {
+        await this.current();
+        const subject = parseStateUri(input.subject);
+        await this.access(subject.collection, 'observe', subject.record);
+        return page(await this.db.query({
+            collection: FELTDB_STATE_OBSERVATION_COLLECTION,
+            where: [{ field: 'tenant_id', eq: this.service.tenantId }, { field: 'contract_id', eq: this.contractId }, { field: 'subject', eq: stateUri(subject) }],
+            orderBy: [{ field: 'recorded_at', direction: 'asc' }],
+            limit: limit(input.limit), ...(input.cursor ? { cursor: input.cursor } : {}),
+        }), row => strip(row));
+    }
+    /**
+     * Declare that a change to `from` may matter to each `to` record.
+     *
+     * A connection is a fact this consumer asserts, with evidence; FeltDB keeps
+     * it, attributes it, and follows it during impact traversal. The consumer
+     * must be able to read both ends; connecting grants nothing on either.
+     */
+    async connect(input) {
+        await this.current();
+        closed(input, ['from', 'to', 'evidence', 'label'], 'connection');
+        const evidence = evidenceList(input.evidence, 'evidence');
+        if (!evidence.length)
+            throw fail('a connection must cite the evidence it was established from');
+        const nodes = [input.from, ...(input.to ?? [])].map(value => parseStateUri(text(value, 'state reference', 2_000)));
+        if (nodes.length < 2)
+            throw fail('a connection needs at least one target');
+        const decisions = [];
+        for (const node of nodes) {
+            if (node.contract !== this.contractId || node.record === undefined)
+                throw fail(`${stateUri(node)} must be a record of contract ${this.contractId}`);
+            decisions.push((await this.access(node.collection, 'read', node.record)).decision);
+        }
+        const from = stateUri(nodes[0]);
+        const edges = [];
+        for (const target of nodes.slice(1)) {
+            const to = stateUri(target);
+            const edgeId = `e.${(await canonicalDigest({ tenant: this.service.tenantId, from, to, relationship: 'connects', declared_by: this.id })).slice(7, 47)}`;
+            edges.push({
+                key: edgeId,
+                edge: {
+                    edge_id: edgeId, tenant_id: this.service.tenantId, contract_id: this.contractId, from, to, relationship: 'connects',
+                    declared_by: this.id, ...(input.label ? { label: text(input.label, 'label', 200) } : {}), evidence,
+                    declared_at: this.service.now(), provenance: this.service.provenance(decisions),
+                },
+            });
+        }
+        const existing = await Promise.all(edges.map(value => this.db.collection(FELTDB_STATE_DEPENDENCY_COLLECTION).get(value.key)));
+        const fresh = edges.filter((_, index) => !existing[index]);
+        if (fresh.length) {
+            await this.db.transaction(async (tx) => {
+                for (const { key, edge } of fresh)
+                    tx.collection(FELTDB_STATE_DEPENDENCY_COLLECTION).set(key, edge, { requireAbsent: true });
+                await this.service.stageTopology(tx);
+            });
+        }
+        return edges.map((value, index) => (existing[index] ? strip(existing[index]) : value.edge));
+    }
+    // ── derived views ──
+    /**
+     * Materialize one of this consumer's declared projections.
+     *
+     * A projection is a runtime snapshot of authoritative state: frozen, with no
+     * write surface, and reporting its staleness. It never becomes authority.
+     */
+    async projection(name) {
+        await this.current();
+        const projection = this.composition.projections.find(value => value.name === name);
+        if (!projection)
+            throw fail(`${this.id} declares no projection ${name}`, FeltDBErrorCode.NOT_FOUND);
+        for (const source of projection.sources)
+            await this.access(source, 'read');
+        const handle = this.db.snapshot({
+            name: `composition/${this.service.tenantId}/${this.contractId}/${this.id}@${this.composition.version}/projection/${name}`,
+            sources: projection.sources.map(collection => ({ collection })),
+        });
+        const snapshot = await handle.refresh();
+        return Object.freeze({
+            uri: `projection://${encodeURIComponent(this.contractId)}/${encodeURIComponent(this.id)}/${encodeURIComponent(name)}`,
+            authoritative: false,
+            derived_from: projection.sources.map(collection => stateUri(this.ref(collection))),
+            identity: snapshot.identity,
+            get: (collection, id) => snapshot.get(collection, id),
+            all: (collection) => snapshot.all(collection),
+            staleness: () => handle.staleness(),
+        });
+    }
+    /**
+     * A consistent, authorized view of the collections this consumer reads,
+     * with the attribution boundary: a change is inside the view exactly when
+     * the view's attribution head for its subject has reached it.
+     */
+    async snapshot(input) {
+        await this.current();
+        const collections = [...new Set(input.collections)].sort();
+        const decisions = [];
+        for (const collection of collections) {
+            const { capability, decision } = await this.access(collection, 'read');
+            decisions.push({ collection, capability, decision_id: decision });
+        }
+        const handle = this.db.snapshot({
+            name: `composition/${this.service.tenantId}/${this.contractId}/${this.id}@${this.composition.version}/view/${collections.join(',')}`,
+            sources: [...collections.map(collection => ({ collection })), {
+                    collection: FELTDB_STATE_ATTRIBUTION_COLLECTION,
+                    where: [{ field: 'tenant_id', eq: this.service.tenantId }, { field: 'contract_id', eq: this.contractId }],
+                }],
+        });
+        const snapshot = await handle.refresh();
+        const heads = new Map(snapshot.all(FELTDB_STATE_ATTRIBUTION_COLLECTION)
+            .filter(row => row.kind !== 'reference' && collections.includes(String(row.collection))).map(row => [String(row.subject), row]));
+        return Object.freeze({
+            contract: this.service.contract,
+            consumer: this.id,
+            composition_version: this.composition.version,
+            authorization: { subject: this.service.subject, entries: decisions },
+            identity: snapshot.identity,
+            coherence: snapshot.basis.coherence,
+            authoritative: false,
+            get: (collection, id) => {
+                if (!collections.includes(collection))
+                    throw forbidden(`${collection} is not part of this view`);
+                const row = snapshot.get(collection, id);
+                const ref = this.ref(collection, id);
+                return { uri: stateUri(ref), ref, exists: Boolean(row), version: recordVersion(row), value: recordValue(row) };
+            },
+            includes: (change) => {
+                if (!collections.includes(change.collection))
+                    throw forbidden(`${change.collection} is not part of this view`);
+                const head = heads.get(change.subject);
+                return Boolean(head) && recordVersion(head) >= change.attribution_version;
+            },
+        });
+    }
+    /** Everything this consumer may learn about the composed contract, for an agent or a person. */
+    async describe() {
+        await this.current();
+        const compositions = await this.service.compositions.list({ limit: 100 });
+        return {
+            contract: this.service.contract,
+            self: this.composition,
+            compositions: compositions.items.map(value => ({ consumer: value.consumer, uri: value.uri, version: value.version, access: value.access, projections: value.projections })),
+            compositions_exhausted: compositions.exhausted,
+            authorized_operations: await this.authorizedOperations(),
+        };
+    }
+    /**
+     * The durable facts around one record: what changed, what is connected to
+     * it and why, what was observed, which projections derive from it, and what
+     * this consumer may do. No interpretation.
+     */
+    async context(uri, input = {}) {
+        const record = parseStateUri(uri);
+        const subject = await this.read(record.collection, record.record);
+        const changes = await this.changes({ collection: record.collection, record: record.record, limit: input.changes ?? 20 });
+        const observations = await this.observations({ subject: uri, limit: input.observations ?? 20 });
+        const { snapshot, binding } = await this.service.basis();
+        const surface = await this.service.impactOf(snapshot, [{ collection: record.collection, id: record.record, value: subject.value ?? {} }]);
+        const readable = new Set();
+        for (const collection of this.service.contract.collections)
+            if (await this.readable(collection))
+                readable.add(collection);
+        const visible = redactImpactSurface(surface, collection => readable.has(collection));
+        return {
+            subject, basis: binding, changes: changes.items, observations: observations.items,
+            connected: visible.dependent, unknown: visible.unknown,
+            authorized_operations: await this.authorizedOperations(),
+        };
+    }
+    // ── understand before mutate ──
+    /** Validate the operations, read the basis, and compute the impact. Writes nothing. */
+    async prepareProposal(input) {
+        const decisions = [];
+        for (const operation of input.operations) {
+            closed(operation, 'delete' in operation ? ['collection', 'id', 'delete'] : ['collection', 'id', 'value'], 'proposed operation');
+            if (!this.service.contract.collections.includes(operation.collection))
+                throw fail(`${operation.collection} is not a collection of contract ${this.contractId}`);
+            // Proposing requires seeing the state; it does not require being able to write it.
+            decisions.push((await this.access(operation.collection, 'read', operation.id)).decision);
+        }
+        const { snapshot, binding, surface, readBasis } = await this.service.anchoredImpact(input.operations);
+        const proposalId = `sp_${crypto.randomUUID().replace(/-/g, '')}`;
+        const impactId = `si_${crypto.randomUUID().replace(/-/g, '')}`;
+        const operations = await Promise.all(input.operations.map(async (operation) => {
+            const row = snapshot.get(operation.collection, operation.id);
+            const value = recordValue(row);
+            return {
+                collection: operation.collection, record_id: operation.id, subject: stateUri(this.ref(operation.collection, operation.id)),
+                operation: 'delete' in operation ? 'delete' : 'set',
+                ...('delete' in operation ? {} : { value: recordValue(operation.value) }),
+                base_version: recordVersion(row), base_value_digest: value === null ? null : await canonicalDigest(value),
+            };
+        }));
+        const provenance = this.service.provenance(decisions);
+        const proposalDigest = await canonicalDigest({ contract: this.service.contract.contract_digest, base: binding.id, operations });
+        const impact = {
+            impact_id: impactId, proposal_id: proposalId, proposal_digest: proposalDigest,
+            tenant_id: this.service.tenantId, contract_id: this.contractId, contract_digest: this.service.contract.contract_digest,
+            base_snapshot: binding, surface, surface_digest: await impactSurfaceDigest(surface), read_basis: readBasis,
+            computed_by: this.id, computed_at: this.service.now(), grants_authority: false, authoritative: false, provenance,
+        };
+        const proposal = {
+            proposal_id: proposalId, intent_id: input.intentId ?? `int_${crypto.randomUUID().replace(/-/g, '')}`,
+            tenant_id: this.service.tenantId, contract_id: this.contractId,
+            contract_digest: this.service.contract.contract_digest, status: 'previewed', proposed_by: this.id,
+            summary: input.summary ? text(input.summary, 'summary') : input.request, operations, proposal_digest: proposalDigest,
+            base_snapshot: binding, impact_id: impactId, impact_digest: impact.surface_digest,
+            ...(input.parent ? { parent_proposal_id: input.parent.proposal_id } : {}),
+            authoritative: false, created_at: this.service.now(), provenance,
+        };
+        return { proposal, impact, actor: `consumer:${this.id}` };
+    }
+    /**
+     * "I propose this state transition."
+     *
+     * Records the intent, the proposal bound to the current basis snapshot, and
+     * the impact surface computed from that same snapshot, in one transaction.
+     * Authoritative state is not touched.
+     */
+    async intend(input) {
+        await this.current();
+        closed(input, ['request', 'summary', 'operations'], 'state intent');
+        const request = text(input.request, 'request');
+        if (!Array.isArray(input.operations) || !input.operations.length)
+            throw fail('a state intent must propose at least one operation');
+        const prepared = await this.prepareProposal({ request, summary: input.summary, operations: input.operations });
+        await this.db.transaction(tx => {
+            const intent = { ...this.service.intentFor(prepared.proposal, request), status: 'proposal_created' };
+            tx.collection(FELTDB_INTENT_COLLECTION).set(intent.id, intent, { requireAbsent: true });
+            this.service.stageIntentEvent(tx, intent.id, 'received', {});
+            this.service.stageIntentEvent(tx, intent.id, 'proposal_created', { proposal_id: prepared.proposal.proposal_id });
+            stageProposalBundle(this.service, tx, prepared);
+        });
+        return this.preview(prepared.proposal.proposal_id);
+    }
+    /**
+     * "What would change if this were applied?"
+     *
+     * The recorded impact, redacted to what this reader may see, with its
+     * current readiness and this reader's authorization evaluated now.
+     */
+    async preview(proposalId) {
+        await this.current();
+        const { proposal, impact } = await this.service.readProposal(proposalId);
+        for (const operation of proposal.operations)
+            await this.access(operation.collection, 'read', operation.record_id);
+        const readable = new Set();
+        for (const collection of this.service.contract.collections)
+            if (await this.readable(collection))
+                readable.add(collection);
+        const authorization = await Promise.all(proposal.operations.map(async (operation) => {
+            const entry = this.entry(operation.collection);
+            const uri = stateUri(this.ref(operation.collection, '*'));
+            return {
+                node: operation.subject, ...(entry ? { capability: entry.capability } : {}),
+                operations: {
+                    write: Boolean(entry && entry.mode !== 'observe') && await this.service.allowed(entry.capability, uri, 'write', this.id),
+                    delete: Boolean(entry && entry.mode === 'own') && await this.service.allowed(entry.capability, uri, 'delete', this.id),
+                },
+            };
+        }));
+        const { read_basis: fence, ...visible } = impact;
+        return {
+            proposal,
+            impact: { ...visible, surface: redactImpactSurface(impact.surface, collection => readable.has(collection)), fenced: Boolean(fence) },
+            readiness: await this.service.readiness(proposalId),
+            authorization,
+            effect: { authoritative: false, state_changes_on: 'apply' },
+        };
+    }
+    /**
+     * The durable record of one proposal: its lifecycle events, its intent and
+     * intent events, the changes its application produced, and its lineage.
+     * Bounded reads; redacted like `preview`.
+     */
+    async history(proposalId, input = {}) {
+        const preview = await this.preview(proposalId);
+        const { proposal } = preview;
+        const bound = limit(input.limit);
+        const byField = async (collection, field, value, order) => (await this.db.query({
+            collection, where: [{ field, eq: value }], orderBy: [{ field: order, direction: 'asc' }], limit: bound,
+        })).records.map(row => strip(row));
+        const changes = (await this.db.query({
+            collection: FELTDB_STATE_CHANGE_COLLECTION,
+            where: [{ field: 'tenant_id', eq: this.service.tenantId }, { field: 'contract_id', eq: this.contractId }, { field: 'proposal_id', eq: proposal.proposal_id }],
+            orderBy: [{ field: 'change_id', direction: 'asc' }], limit: bound,
+        })).records.map(row => strip(row));
+        const intentRow = await this.db.collection(FELTDB_INTENT_COLLECTION).get(proposal.intent_id);
+        return {
+            proposal, impact: preview.impact, readiness: preview.readiness,
+            // Events committed together share a timestamp; the lifecycle order breaks the tie.
+            events: (await byField(FELTDB_PROPOSAL_EVENT_COLLECTION, 'proposal_id', proposal.proposal_id, 'created_at'))
+                .sort((left, right) => String(left.created_at).localeCompare(String(right.created_at)) || LIFECYCLE_RANK[left.to_status] - LIFECYCLE_RANK[right.to_status]),
+            intent: intentRow ? { ...strip(intentRow), id: String(intentRow.id) } : null,
+            intent_events: await byField(FELTDB_INTENT_EVENT_COLLECTION, 'intent_id', proposal.intent_id, 'created_at'),
+            changes,
+            lineage: {
+                ...(proposal.parent_proposal_id ? { parent_proposal_id: proposal.parent_proposal_id } : {}),
+                ...(proposal.superseded_by ? { superseded_by: proposal.superseded_by } : {}),
+            },
+        };
+    }
+    /**
+     * Re-propose the same operations against the current snapshot.
+     *
+     * The stale proposal is retired through the shared lifecycle, and the child
+     * proposal gets a fresh impact. Nothing carries over except lineage.
+     */
+    async rebase(proposalId) {
+        await this.current();
+        const { proposal, row } = await this.service.readProposal(proposalId);
+        if (!['proposed', 'validated', 'previewed', 'approved'].includes(proposal.status))
+            throw fail(`State proposal ${proposalId} is ${proposal.status}`, FeltDBErrorCode.CONFLICT);
+        const intentRow = await this.db.collection(FELTDB_INTENT_COLLECTION).get(proposal.intent_id);
+        const prepared = await this.prepareProposal({
+            request: proposal.summary, summary: proposal.summary, operations: toOperations(proposal), parent: proposal, intentId: proposal.intent_id,
+        });
+        await this.db.transaction(tx => {
+            this.service.stageProposalMove(tx, { ...proposal, superseded_by: prepared.proposal.proposal_id }, row, proposal.status === 'approved' ? 'expired' : 'rejected', `consumer:${this.id}`, { reason: 'rebased', child_proposal_id: prepared.proposal.proposal_id });
+            stageProposalBundle(this.service, tx, prepared);
+            if (intentRow) {
+                const intent = strip(intentRow);
+                this.service.stageIntent(tx, { ...intent, id: String(intentRow.id), proposal_id: prepared.proposal.proposal_id }, intentRow, 'proposal_created', { proposal_id: prepared.proposal.proposal_id, parent_proposal_id: proposal.proposal_id });
+            }
+        });
+        return this.preview(prepared.proposal.proposal_id);
+    }
+    /**
+     * Make an approved proposal authoritative.
+     *
+     * The impact is re-derived from a current snapshot and must equal the
+     * approved one; every direct write is CAS-guarded on the proposal's base
+     * version; the topology head is fenced; the gate authorizes every write for
+     * this consumer. State, attribution, proposal, and intent commit together.
+     */
+    async apply(proposalId, options = {}) {
+        await this.current();
+        const { proposal, row, impact, readiness } = await this.service.assess(proposalId);
+        if (proposal.status !== 'approved' || !proposal.approval)
+            throw fail(`State proposal ${proposalId} is ${proposal.status}; only an approved proposal can be applied`, FeltDBErrorCode.CONFLICT);
+        if (proposal.approval.impact_id !== impact.impact_id || proposal.approval.impact_digest !== impact.surface_digest) {
+            throw fail(`The approval of ${proposalId} does not bind its impact`, FeltDBErrorCode.CONFLICT);
+        }
+        const transactionId = `apply_${proposal.proposal_id}`;
+        if (readiness.stale) {
+            await this.recordRefusal(proposal, transactionId, readiness.blockers.join(','));
+            throw fail(`State proposal ${proposalId} was analyzed against ${proposal.base_snapshot.id}; authoritative state has since changed `
+                + `(${readiness.blockers.join(', ')}). Rebase and review it again.`, FeltDBErrorCode.VERSION_CONFLICT);
+        }
+        const intentRow = await this.db.collection(FELTDB_INTENT_COLLECTION).get(proposal.intent_id);
+        const writes = proposal.operations.map(operation => ({
+            collection: operation.collection, id: operation.record_id,
+            ...(operation.operation === 'set' ? { value: operation.value } : {}),
+            expected: { version: operation.base_version },
+        }));
+        try {
+            return await this.commit(writes, {
+                transactionId,
+                causalId: options.causalId ?? proposal.intent_id,
+                proposal,
+                // The authority re-reads exactly the state the approved impact was
+                // computed from, inside its commit decision, and refuses the whole
+                // transaction if any of it changed — whichever write path changed it.
+                fences: [impact.read_basis],
+                stage: (tx, changes, committed) => {
+                    this.service.stageProposalMove(tx, {
+                        ...proposal,
+                        applied: {
+                            transaction_id: committed, change_ids: changes.map(value => value.change_id), applied_by: this.id,
+                            applied_at: this.service.now(), apply_snapshot: readiness.current_snapshot,
+                        },
+                    }, row, 'applied', `consumer:${this.id}`, { transaction_id: committed, impact_id: impact.impact_id, read_basis: impact.read_basis.token });
+                    if (intentRow) {
+                        const intent = strip(intentRow);
+                        this.service.stageIntent(tx, { ...intent, id: String(intentRow.id) }, intentRow, 'completed', { proposal_id: proposal.proposal_id, transaction_id: committed });
+                    }
+                },
+            });
+        }
+        catch (error) {
+            const refusal = conditionalRefusal(error);
+            const lostRace = refusal.conflict
+                || (error instanceof AtomicTransactionError && /conflict|PRECONDITION_FAILED/i.test(`${error.name} ${error.code ?? ''}`))
+                || (error instanceof FeltDBServiceError && error.code === FeltDBErrorCode.VERSION_CONFLICT);
+            if (!lostRace)
+                throw error;
+            const predicate = error.failure?.predicate ?? (refusal.conflict ? refusal.failure?.predicate : undefined) ?? 'version';
+            await this.recordRefusal(proposal, transactionId, predicate === 'fence' ? 'read_basis_changed' : `precondition_${predicate}`);
+            throw fail(`State proposal ${proposalId}: authoritative state it was approved against changed before the commit `
+                + `(${predicate}). Nothing was applied; rebase and review it again.`, FeltDBErrorCode.VERSION_CONFLICT);
+        }
+    }
+    /**
+     * Record a refused apply in the proposal's history, in its own transaction.
+     *
+     * The refused commit wrote nothing; this is the audit trail that it was
+     * attempted and why it was refused. The proposal record itself is unchanged.
+     */
+    async recordRefusal(proposal, transactionId, reason) {
+        await this.db.transaction(tx => {
+            this.service.stageProposalEvent(tx, proposal.proposal_id, proposal.status, proposal.status, `consumer:${this.id}`, {
+                outcome: 'apply_refused', reason, transaction_id: transactionId,
+            });
+        });
+    }
+}
+/** Stage a proposal born `previewed`, its impact, and its lifecycle history. */
+function stageProposalBundle(service, tx, prepared) {
+    const { proposal, impact, actor } = prepared;
+    tx.collection(FELTDB_STATE_IMPACT_COLLECTION).set(service.proposalKey(impact.impact_id), impact, { requireAbsent: true });
+    tx.collection(FELTDB_STATE_PROPOSAL_COLLECTION).set(service.proposalKey(proposal.proposal_id), proposal, { requireAbsent: true });
+    service.stageProposalEvent(tx, proposal.proposal_id, undefined, 'proposed', actor, { intent_id: proposal.intent_id });
+    service.stageProposalEvent(tx, proposal.proposal_id, 'proposed', 'validated', actor, {});
+    service.stageProposalEvent(tx, proposal.proposal_id, 'validated', 'previewed', actor, { impact_id: impact.impact_id, base_snapshot: proposal.base_snapshot.id });
+}