@feltdb/core 0.11.3 → 0.11.5

package/dist/architecture-invariant.js

@@ -0,0 +1,708 @@
+/**
+ * Architecture invariants.
+ *
+ *     application / human
+ *          │  declares
+ *          ▼
+ *     FeltDB  ──── invariant (identity, declaration, version, lifecycle, provenance)
+ *          │                                        │
+ *          │ snapshot                               │ referenced by exact version
+ *          ▼                                        ▼
+ *     evaluator (jev, or any other)  ────────▶  evaluation (PASS | DRIFT | UNKNOWN)
+ *                                                   │
+ *                                                   ▼
+ *                                                 FeltDB
+ *
+ * An architecture invariant is a durable declaration that some condition is
+ * expected to remain true of an application: across code, contracts,
+ * configuration, endpoints, secrets, authority boundaries, or any other
+ * architectural surface.
+ *
+ * FeltDB owns the declaration. It stores invariant identity, the versioned
+ * declaration, lifecycle, provenance, and the durable history of what was
+ * evaluated. It does not decide whether an invariant is currently satisfied,
+ * and it contains no evaluator.
+ *
+ * An evaluator owns the judgment. It reads a declaration snapshot, collects
+ * evidence, and records an advisory evaluation against the exact invariant
+ * version it read. `evaluations.record()` can only write evaluations: the
+ * store it is given rejects a write to any other collection, so an evaluator
+ * cannot redefine, reword, or retire the invariant it was asked about, and a
+ * DRIFT result never changes the declaration it drifted from.
+ *
+ * An invariant references the authorities it constrains; it never restates
+ * them. `.flow` remains authoritative for its contract and configuration
+ * model, AppPort for AppPort contracts, AuthBoundry for authorization
+ * decisions, and FeltDB for durable application state. A reference names the
+ * authority and states the relationship that must remain true about it.
+ */
+import { canonicalApplicationBytes } from './canonical-application.js';
+import { FeltDBErrorCode, FeltDBServiceError } from './error-codes.js';
+/** Durable collection holding one head record per declared invariant. */
+export const FELTDB_ARCHITECTURE_INVARIANT_COLLECTION = '_feltdb.ArchitectureInvariant';
+/** Durable collection holding the immutable declaration of every version. */
+export const FELTDB_ARCHITECTURE_INVARIANT_VERSION_COLLECTION = '_feltdb.ArchitectureInvariantVersion';
+/** Durable collection holding immutable advisory evaluations. */
+export const FELTDB_ARCHITECTURE_EVALUATION_COLLECTION = '_feltdb.ArchitectureInvariantEvaluation';
+export const ARCHITECTURE_INVARIANT_CONTRACT_VERSION = 1;
+/** Largest page a bounded invariant or evaluation query may request. */
+export const ARCHITECTURE_INVARIANT_MAX_LIMIT = 1_000;
+/** Page size used when a caller does not request one. */
+export const ARCHITECTURE_INVARIANT_DEFAULT_LIMIT = 100;
+export const ARCHITECTURE_INVARIANT_SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'];
+export const ARCHITECTURE_INVARIANT_STATUSES = ['active', 'inactive'];
+/**
+ * How an invariant can be established.
+ *
+ * Not every invariant is mechanically checkable. Some are decided by a test or
+ * a conformance check, some need evidence interpreted by an advisory
+ * evaluator, and some can only be escalated to a person. All three are
+ * first-class: `human-review` is a complete answer to "how is this verified",
+ * not an admission that the model failed to describe it.
+ */
+export const ARCHITECTURE_VERIFICATION_METHODS = [
+    'automated-test', 'contract-conformance', 'source-analysis',
+    'runtime-observation', 'benchmark', 'jev-advisory', 'human-review',
+];
+/**
+ * Advisory results an evaluator may record.
+ *
+ * `UNKNOWN` exists so that missing evidence stays missing evidence. An
+ * evaluator that cannot establish a condition records `UNKNOWN`; it does not
+ * record `DRIFT`, and FeltDB never promotes one to the other.
+ */
+export const ARCHITECTURE_EVALUATION_RESULTS = ['PASS', 'DRIFT', 'UNKNOWN'];
+export const ARCHITECTURE_INVARIANT_CAPABILITIES = {
+    declare: 'architecture:invariant.declare',
+    read: 'architecture:invariant.read',
+    evaluate: 'architecture:evaluation.record',
+    readEvaluation: 'architecture:evaluation.read',
+};
+/**
+ * Declaration fields an evaluation may never carry.
+ *
+ * An evaluator states what it observed. The moment its output could also carry
+ * a `severity` or a `description`, recording an evaluation would be a way to
+ * redefine the invariant, and the authority boundary would be advisory in name
+ * only. These are rejected rather than ignored, so a caller that believes it
+ * is changing the declaration finds out.
+ */
+const EVALUATION_FORBIDDEN_FIELDS = [
+    'name', 'description', 'category', 'severity', 'scope', 'status',
+    'verification', 'references', 'version', 'declaration_digest', 'provenance',
+];
+const EVIDENCE_REFERENCE = /^[a-z][a-z0-9+.-]*:.+$/;
+function invalid(message) {
+    return new FeltDBServiceError(message, FeltDBErrorCode.VALIDATION_ERROR);
+}
+function requireText(value, label, max = 4_000) {
+    if (typeof value !== 'string' || !value.trim())
+        throw invalid(`${label} must be a non-empty string`);
+    const text = value.trim();
+    if (text.length > max)
+        throw invalid(`${label} must be at most ${max} characters`);
+    return text;
+}
+/**
+ * Identities become durable record keys, so a separator inside one would let
+ * two different declarations resolve to the same row.
+ */
+function requireIdentity(value, label) {
+    const text = requireText(value, label, 200);
+    if (/[:/\s]/.test(text))
+        throw invalid(`${label} must not contain ":", "/", or whitespace`);
+    return text;
+}
+function requireMember(value, allowed, label) {
+    if (typeof value !== 'string' || !allowed.includes(value)) {
+        throw invalid(`${label} must be one of ${allowed.join(', ')}`);
+    }
+    return value;
+}
+function normalizeEvidence(value, label) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw invalid(`${label} must be an array of evidence references`);
+    const seen = new Set();
+    for (const entry of value) {
+        const reference = requireText(entry, `${label} entry`, 1_000);
+        if (!EVIDENCE_REFERENCE.test(reference)) {
+            throw invalid(`${label} entry "${reference}" must be a "scheme:reference" evidence reference`);
+        }
+        seen.add(reference);
+    }
+    return [...seen];
+}
+/**
+ * An invariant must say how it can be established, even when the answer is
+ * that only a person can decide it. An invariant nobody can verify by any
+ * means is a sentence, not an invariant.
+ */
+function normalizeVerification(value, label) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw invalid(`${label} must declare at least one way this invariant can be established`);
+    }
+    return value.map((entry, position) => {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+            throw invalid(`${label}[${position}] must be an object`);
+        }
+        const input = entry;
+        const reference = input.reference === undefined ? undefined : requireText(input.reference, `${label}[${position}].reference`, 1_000);
+        if (reference !== undefined && !EVIDENCE_REFERENCE.test(reference)) {
+            throw invalid(`${label}[${position}].reference must be a "scheme:reference" evidence reference`);
+        }
+        return {
+            method: requireMember(input.method, ARCHITECTURE_VERIFICATION_METHODS, `${label}[${position}].method`),
+            ...(reference === undefined ? {} : { reference }),
+            ...(input.evaluator === undefined ? {} : { evaluator: requireText(input.evaluator, `${label}[${position}].evaluator`, 200) }),
+            ...(input.predicate === undefined ? {} : { predicate: requireText(input.predicate, `${label}[${position}].predicate`) }),
+            ...(input.notes === undefined ? {} : { notes: requireText(input.notes, `${label}[${position}].notes`) }),
+            ...(input.parameters === undefined ? {} : (() => {
+                if (typeof input.parameters !== 'object' || input.parameters === null || Array.isArray(input.parameters)) {
+                    throw invalid(`${label}[${position}].parameters must be an object`);
+                }
+                return { parameters: input.parameters };
+            })()),
+        };
+    });
+}
+function normalizeReferences(value, label) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw invalid(`${label} must be an array`);
+    return value.map((entry, position) => {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+            throw invalid(`${label}[${position}] must be an object`);
+        }
+        const reference = entry;
+        return {
+            authority: requireText(reference.authority, `${label}[${position}].authority`, 200),
+            reference: requireText(reference.reference, `${label}[${position}].reference`, 1_000),
+            relationship: requireText(reference.relationship, `${label}[${position}].relationship`),
+        };
+    });
+}
+function normalizeDeclaration(input) {
+    return {
+        name: requireText(input.name, 'name', 300),
+        description: requireText(input.description, 'description'),
+        category: requireIdentity(input.category, 'category'),
+        severity: requireMember(input.severity, ARCHITECTURE_INVARIANT_SEVERITIES, 'severity'),
+        scope: requireIdentity(input.scope, 'scope'),
+        verification: normalizeVerification(input.verification, 'verification'),
+        references: normalizeReferences(input.references, 'references'),
+    };
+}
+function declarationOf(value) {
+    return {
+        name: value.name,
+        description: value.description,
+        category: value.category,
+        severity: value.severity,
+        scope: value.scope,
+        verification: value.verification,
+        references: value.references,
+    };
+}
+/**
+ * Digest over the canonical application encoding FeltDB already uses, so an
+ * evaluation can prove which words it was evaluating.
+ */
+async function declarationDigest(declaration) {
+    const bytes = canonicalApplicationBytes(declaration);
+    const digest = await crypto.subtle.digest('SHA-256', bytes.slice().buffer);
+    return `sha256:${Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, '0')).join('')}`;
+}
+function sameDeclaration(left, right) {
+    const encode = (value) => new TextDecoder().decode(canonicalApplicationBytes(value));
+    return encode(declarationOf(left)) === encode(declarationOf(right));
+}
+function boundedLimit(value) {
+    if (value === undefined)
+        return ARCHITECTURE_INVARIANT_DEFAULT_LIMIT;
+    if (!Number.isInteger(value) || value < 1 || value > ARCHITECTURE_INVARIANT_MAX_LIMIT) {
+        throw new FeltDBServiceError(`limit must be an integer between 1 and ${ARCHITECTURE_INVARIANT_MAX_LIMIT}`, FeltDBErrorCode.QUERY_LIMIT_EXCEEDED);
+    }
+    return value;
+}
+function timestamp(value) {
+    return value.toISOString();
+}
+function resolveEvaluatedAt(value, fallback) {
+    if (value === undefined)
+        return timestamp(fallback);
+    const resolved = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(resolved.getTime()))
+        throw invalid('evaluatedAt must be a valid date');
+    return timestamp(resolved);
+}
+/**
+ * A store that can only write one collection.
+ *
+ * `evaluations.record()` runs against this, which is what makes "an evaluation
+ * cannot mutate an invariant" a property of the substrate rather than a rule
+ * the recording path is trusted to follow.
+ */
+export function restrictWritesTo(store, collection) {
+    const guard = (target) => {
+        if (target !== collection) {
+            throw new FeltDBServiceError(`An evaluator may only write ${collection}; ${target} is owned by the declaring authority`, FeltDBErrorCode.FORBIDDEN);
+        }
+    };
+    return {
+        read: (target, recordId) => store.read(target, recordId),
+        query: request => store.query(request),
+        create: async (target, recordId, value) => { guard(target); return store.create(target, recordId, value); },
+        replace: async (target, recordId, value) => { guard(target); return store.replace(target, recordId, value); },
+    };
+}
+/** Adapt a FeltDB instance to the durable substrate this service writes through. */
+export function createArchitectureInvariantStore(db) {
+    return {
+        async read(collection, recordId) {
+            return (await db.collection(collection).get(recordId)) ?? undefined;
+        },
+        async create(collection, recordId, value) {
+            await db.collection(collection).insert(value, recordId);
+        },
+        async replace(collection, recordId, value) {
+            await db.collection(collection).update(recordId, value);
+        },
+        query: request => db.query(request),
+    };
+}
+function toInvariant(row) {
+    const { invariant_id, id: _recordId, __version: _rowVersion, ...rest } = row;
+    return { ...rest, id: invariant_id };
+}
+function toEvaluation(row) {
+    const { evaluation_id, id: _recordId, __version: _rowVersion, evaluator_id: _evaluatorId, ...rest } = row;
+    return { ...rest, id: evaluation_id };
+}
+function toVersion(row) {
+    const { id: _recordId, __version: _rowVersion, ...rest } = row;
+    return rest;
+}
+/**
+ * The durable architecture invariant substrate.
+ *
+ * `invariants` declares what must be true. `evaluations` retains what an
+ * advisory evaluator observed about it. Neither side can do the other's job.
+ */
+export class FeltDBArchitectureInvariantService {
+    scope;
+    actor;
+    source;
+    authorization;
+    clock;
+    newEvaluationId;
+    evaluationStore;
+    store;
+    constructor(store, options) {
+        this.store = store;
+        this.scope = {
+            tenantId: requireIdentity(options.scope?.tenantId, 'scope.tenantId'),
+            applicationId: requireIdentity(options.scope?.applicationId, 'scope.applicationId'),
+        };
+        if (!options.actor?.id || !options.actor?.kind)
+            throw invalid('actor requires a subject kind and id');
+        this.actor = { kind: options.actor.kind, id: requireText(options.actor.id, 'actor.id', 200) };
+        this.source = requireText(options.source, 'source', 200);
+        this.authorization = options.authorization;
+        this.clock = options.now ?? (() => new Date());
+        this.newEvaluationId = options.newEvaluationId ?? (() => `ae_${crypto.randomUUID().replace(/-/g, '')}`);
+        this.evaluationStore = restrictWritesTo(store, FELTDB_ARCHITECTURE_EVALUATION_COLLECTION);
+    }
+    /** Durable record key. Scoping by tenant and application is part of identity. */
+    scopedKey(recordId) {
+        return `${this.scope.tenantId}/${this.scope.applicationId}/${recordId}`;
+    }
+    versionKey(invariantId, version) {
+        return `${this.scopedKey(invariantId)}@${version}`;
+    }
+    resourceUri(collection, recordId) {
+        return `flow://${this.scope.applicationId}/${collection}/${recordId}`;
+    }
+    /**
+     * Ask FeltDB's existing authorization boundary, and fail closed.
+     *
+     * With no gate configured the caller has not asked for narrowing, and this
+     * substrate must not invent an authorization answer FeltDB did not give.
+     */
+    async authorize(capability, collection, recordId) {
+        if (!this.authorization)
+            return undefined;
+        const decision = await this.authorization.gate.check({
+            subject: this.authorization.subject,
+            tenant_id: this.scope.tenantId,
+            application_id: this.scope.applicationId,
+            resource: { uri: this.resourceUri(collection, recordId) },
+            capability,
+            context: { timestamp: this.clock().getTime() },
+        });
+        if (decision?.allowed !== true) {
+            throw new FeltDBServiceError(`${capability} was not allowed for ${this.resourceUri(collection, recordId)}${decision?.reason ? `: ${decision.reason}` : ''}`, FeltDBErrorCode.FORBIDDEN);
+        }
+        return decision.decision_id;
+    }
+    provenance(decisionId, at) {
+        return {
+            subject: this.authorization?.subject ?? this.actor,
+            tenant_id: this.scope.tenantId,
+            application_id: this.scope.applicationId,
+            recorded_at: timestamp(at),
+            source: this.source,
+            ...(decisionId ? { authorization_decision_id: decisionId } : {}),
+        };
+    }
+    async readInvariantRow(invariantId) {
+        const row = await this.store.read(FELTDB_ARCHITECTURE_INVARIANT_COLLECTION, this.scopedKey(invariantId));
+        if (!row || row.tenant_id !== this.scope.tenantId || row.application_id !== this.scope.applicationId) {
+            throw new FeltDBServiceError(`Architecture invariant ${invariantId} was not found`, FeltDBErrorCode.NOT_FOUND);
+        }
+        return row;
+    }
+    /**
+     * Every collection read is a bounded, tenant- and application-scoped query
+     * with an explicit order, so a page is reproducible and a cursor resumes
+     * where the previous page ended instead of rescanning the collection.
+     */
+    scopedQuery(collection, where, orderBy, limit, cursor) {
+        return {
+            collection,
+            where: [
+                { field: 'tenant_id', eq: this.scope.tenantId },
+                { field: 'application_id', eq: this.scope.applicationId },
+                ...(where ?? []),
+            ],
+            orderBy,
+            limit,
+            ...(cursor ? { cursor } : {}),
+        };
+    }
+    async writeVersion(invariantId, version, declaration, digest, at, provenance, supersedes, reason) {
+        const record = {
+            id: this.versionKey(invariantId, version),
+            invariant_id: invariantId,
+            tenant_id: this.scope.tenantId,
+            application_id: this.scope.applicationId,
+            contract_version: ARCHITECTURE_INVARIANT_CONTRACT_VERSION,
+            version,
+            ...declaration,
+            declaration_digest: digest,
+            ...(supersedes === undefined ? {} : { supersedes }),
+            ...(reason ? { change_reason: reason } : {}),
+            declared_at: timestamp(at),
+            declared_by: provenance.subject,
+            provenance,
+        };
+        await this.store.create(FELTDB_ARCHITECTURE_INVARIANT_VERSION_COLLECTION, record.id, record);
+        return toVersion(record);
+    }
+    invariants = {
+        /** Declare an invariant. The declaration becomes version 1. */
+        create: async (input) => {
+            const invariantId = requireIdentity(input?.id, 'id');
+            const declaration = normalizeDeclaration(input);
+            const decisionId = await this.authorize(ARCHITECTURE_INVARIANT_CAPABILITIES.declare, FELTDB_ARCHITECTURE_INVARIANT_COLLECTION, invariantId);
+            const key = this.scopedKey(invariantId);
+            if (await this.store.read(FELTDB_ARCHITECTURE_INVARIANT_COLLECTION, key)) {
+                throw new FeltDBServiceError(`Architecture invariant ${invariantId} is already declared for this application`, FeltDBErrorCode.CONFLICT);
+            }
+            const at = this.clock();
+            const provenance = this.provenance(decisionId, at);
+            const digest = await declarationDigest(declaration);
+            const row = {
+                id: key,
+                invariant_id: invariantId,
+                tenant_id: this.scope.tenantId,
+                application_id: this.scope.applicationId,
+                contract_version: ARCHITECTURE_INVARIANT_CONTRACT_VERSION,
+                ...declaration,
+                status: 'active',
+                version: 1,
+                declaration_digest: digest,
+                created_at: timestamp(at),
+                created_by: provenance.subject,
+                updated_at: timestamp(at),
+                updated_by: provenance.subject,
+                provenance,
+            };
+            await this.writeVersion(invariantId, 1, declaration, digest, at, provenance);
+            await this.store.create(FELTDB_ARCHITECTURE_INVARIANT_COLLECTION, key, row);
+            return toInvariant(row);
+        },
+        /** Read the current declaration. */
+        get: async (invariantId) => {
+            const id = requireIdentity(invariantId, 'id');
+            await this.authorize(ARCHITECTURE_INVARIANT_CAPABILITIES.read, FELTDB_ARCHITECTURE_INVARIANT_COLLECTION, id);
+            return toInvariant(await this.readInvariantRow(id));
+        },
+        /** Read one immutable declaration version. */
+        version: async (invariantId, version) => {
+            const id = requireIdentity(invariantId, 'id');
+            if (!Number.isInteger(version) || version < 1)
+                throw invalid('version must be a positive integer');
+            await this.authorize(ARCHITECTURE_INVARIANT_CAPABILITIES.read, FELTDB_ARCHITECTURE_INVARIANT_COLLECTION, id);
+            const row = await this.store.read(FELTDB_ARCHITECTURE_INVARIANT_VERSION_COLLECTION, this.versionKey(id, version));
+            if (!row || row.tenant_id !== this.scope.tenantId || row.application_id !== this.scope.applicationId) {
+                throw new FeltDBServiceError(`Architecture invariant ${id} has no version ${version}`, FeltDBErrorCode.NOT_FOUND);
+            }
+            return toVersion(row);
+        },
+        /** Page the declaration history of one invariant, oldest version first. */
+        versions: async (invariantId, input = {}) => {
+            const id = requireIdentity(invariantId, 'id');
+            await this.authorize(ARCHITECTURE_INVARIANT_CAPABILITIES.read, FELTDB_ARCHITECTURE_INVARIANT_COLLECTION, id);
+            const page = await this.store.query(this.scopedQuery(FELTDB_ARCHITECTURE_INVARIANT_VERSION_COLLECTION, [{ field: 'invariant_id', eq: id }], [{ field: 'version', direction: 'asc' }], boundedLimit(input.limit), input.cursor));
+            return {
+                versions: page.records.map(toVersion),
+                ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+                exhausted: page.exhausted,
+            };
+        },
+        /** Page declared invariants within this tenant and application. */
+        list: async (input = {}) => {
+            await this.authorize(ARCHITECTURE_INVARIANT_CAPABILITIES.read, FELTDB_ARCHITECTURE_INVARIANT_COLLECTION, '*');
+            const where = [];
+            if (input.status !== undefined)
+                where.push({ field: 'status', eq: requireMember(input.status, ARCHITECTURE_INVARIANT_STATUSES, 'status') });
+            if (input.category !== undefined)
+                where.push({ field: 'category', eq: requireIdentity(input.category, 'category') });
+            if (input.severity !== undefined)
+                where.push({ field: 'severity', eq: requireMember(input.severity, ARCHITECTURE_INVARIANT_SEVERITIES, 'severity') });
+            if (input.scope !== undefined)
+                where.push({ field: 'scope', eq: requireIdentity(input.scope, 'scope') });
+            const page = await this.store.query(this.scopedQuery(FELTDB_ARCHITECTURE_INVARIANT_COLLECTION, where, [{ field: 'invariant_id', direction: 'asc' }], boundedLimit(input.limit), input.cursor));
+            return {
+                invariants: page.records.map(toInvariant),
+                ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+                exhausted: page.exhausted,
+            };
+        },
+        /**
+         * Change what an invariant means.
+         *
+         * A changed declaration becomes a new version; the previous version keeps
+         * its exact words, so evaluations recorded against it stay readable. An
+         * update that changes nothing is a no-op and creates no version.
+         */
+        update: async (invariantId, input = {}) => {
+            const id = requireIdentity(invariantId, 'id');
+            const decisionId = await this.authorize(ARCHITECTURE_INVARIANT_CAPABILITIES.declare, FELTDB_ARCHITECTURE_INVARIANT_COLLECTION, id);
+            const row = await this.readInvariantRow(id);
+            if (input.expectedVersion !== undefined && input.expectedVersion !== row.version) {
+                throw new FeltDBServiceError(`Architecture invariant ${id} is at version ${row.version}, not ${input.expectedVersion}`, FeltDBErrorCode.VERSION_CONFLICT);
+            }
+            if (row.status !== 'active') {
+                throw new FeltDBServiceError(`Architecture invariant ${id} is ${row.status} and cannot be redeclared`, FeltDBErrorCode.CONFLICT);
+            }
+            const declaration = normalizeDeclaration({
+                ...declarationOf(row),
+                ...(input.name === undefined ? {} : { name: input.name }),
+                ...(input.description === undefined ? {} : { description: input.description }),
+                ...(input.category === undefined ? {} : { category: input.category }),
+                ...(input.severity === undefined ? {} : { severity: input.severity }),
+                ...(input.scope === undefined ? {} : { scope: input.scope }),
+                ...(input.verification === undefined ? {} : { verification: input.verification }),
+                ...(input.references === undefined ? {} : { references: input.references }),
+            });
+            if (sameDeclaration(row, declaration))
+                return toInvariant(row);
+            const at = this.clock();
+            const provenance = this.provenance(decisionId, at);
+            const version = row.version + 1;
+            const digest = await declarationDigest(declaration);
+            await this.writeVersion(id, version, declaration, digest, at, provenance, row.version, input.reason);
+            const updated = {
+                ...row,
+                ...declaration,
+                version,
+                declaration_digest: digest,
+                updated_at: timestamp(at),
+                updated_by: provenance.subject,
+                provenance,
+            };
+            await this.store.replace(FELTDB_ARCHITECTURE_INVARIANT_COLLECTION, row.id, updated);
+            return toInvariant(updated);
+        },
+        /**
+         * Retire an invariant without rewriting it.
+         *
+         * Deactivation is lifecycle, not meaning: the declaration keeps its
+         * version, and evaluations recorded against it remain readable.
+         */
+        deactivate: async (invariantId, input = {}) => {
+            const id = requireIdentity(invariantId, 'id');
+            const decisionId = await this.authorize(ARCHITECTURE_INVARIANT_CAPABILITIES.declare, FELTDB_ARCHITECTURE_INVARIANT_COLLECTION, id);
+            const row = await this.readInvariantRow(id);
+            if (input.expectedVersion !== undefined && input.expectedVersion !== row.version) {
+                throw new FeltDBServiceError(`Architecture invariant ${id} is at version ${row.version}, not ${input.expectedVersion}`, FeltDBErrorCode.VERSION_CONFLICT);
+            }
+            if (row.status === 'inactive')
+                return toInvariant(row);
+            const at = this.clock();
+            const provenance = this.provenance(decisionId, at);
+            const updated = {
+                ...row,
+                status: 'inactive',
+                updated_at: timestamp(at),
+                updated_by: provenance.subject,
+                deactivated_at: timestamp(at),
+                deactivated_by: provenance.subject,
+                ...(input.reason ? { deactivation_reason: requireText(input.reason, 'reason') } : {}),
+                provenance,
+            };
+            await this.store.replace(FELTDB_ARCHITECTURE_INVARIANT_COLLECTION, row.id, updated);
+            return toInvariant(updated);
+        },
+    };
+    evaluations = {
+        /**
+         * Retain one advisory evaluation.
+         *
+         * The evaluation binds to the exact invariant version it names, and to
+         * that version's declaration digest. A conclusive result must cite
+         * evidence; `UNKNOWN` need not, because the absence of evidence is what it
+         * reports.
+         */
+        record: async (input) => {
+            if (!input || typeof input !== 'object')
+                throw invalid('an evaluation input object is required');
+            const supplied = Object.keys(input);
+            const forbidden = EVALUATION_FORBIDDEN_FIELDS.filter(field => supplied.includes(field));
+            if (forbidden.length) {
+                throw new FeltDBServiceError(`An evaluation may not carry invariant declaration fields (${forbidden.join(', ')}); `
+                    + 'the declaring authority owns the invariant definition', FeltDBErrorCode.FORBIDDEN);
+            }
+            const invariantId = requireIdentity(input.invariantId, 'invariantId');
+            if (!Number.isInteger(input.invariantVersion) || input.invariantVersion < 1) {
+                throw invalid('invariantVersion must be a positive integer');
+            }
+            const result = requireMember(input.result, ARCHITECTURE_EVALUATION_RESULTS, 'result');
+            const explanation = requireText(input.explanation, 'explanation');
+            const evidence = normalizeEvidence(input.evidence, 'evidence');
+            if (result !== 'UNKNOWN' && evidence.length === 0) {
+                throw invalid(`a ${result} evaluation must reference the evidence it was derived from`);
+            }
+            if (input.confidence !== undefined
+                && (typeof input.confidence !== 'number' || !Number.isFinite(input.confidence)
+                    || input.confidence < 0 || input.confidence > 1)) {
+                throw invalid('confidence must be a number between 0 and 1');
+            }
+            const findings = (input.findings ?? []).map((finding, position) => {
+                const supporting = normalizeEvidence(finding?.evidence, `findings[${position}].evidence`);
+                return {
+                    summary: requireText(finding?.summary, `findings[${position}].summary`),
+                    ...(finding?.severity === undefined ? {} : {
+                        severity: requireMember(finding.severity, ARCHITECTURE_INVARIANT_SEVERITIES, `findings[${position}].severity`),
+                    }),
+                    ...(supporting.length ? { evidence: supporting } : {}),
+                };
+            });
+            const evaluationId = input.evaluationId === undefined
+                ? this.newEvaluationId()
+                : requireIdentity(input.evaluationId, 'evaluationId');
+            const decisionId = await this.authorize(ARCHITECTURE_INVARIANT_CAPABILITIES.evaluate, FELTDB_ARCHITECTURE_EVALUATION_COLLECTION, evaluationId);
+            // The declaration is read, never written: the version must already exist,
+            // and the evaluation carries its digest so the words can be proved later.
+            const declared = await this.evaluationStore.read(FELTDB_ARCHITECTURE_INVARIANT_VERSION_COLLECTION, this.versionKey(invariantId, input.invariantVersion));
+            if (!declared || declared.tenant_id !== this.scope.tenantId || declared.application_id !== this.scope.applicationId) {
+                throw new FeltDBServiceError(`Architecture invariant ${invariantId} has no version ${input.invariantVersion} to evaluate`, FeltDBErrorCode.NOT_FOUND);
+            }
+            const key = this.scopedKey(evaluationId);
+            if (await this.evaluationStore.read(FELTDB_ARCHITECTURE_EVALUATION_COLLECTION, key)) {
+                throw new FeltDBServiceError(`Evaluation ${evaluationId} is already recorded`, FeltDBErrorCode.IDEMPOTENCY_CONFLICT);
+            }
+            const at = this.clock();
+            const row = {
+                id: key,
+                evaluation_id: evaluationId,
+                tenant_id: this.scope.tenantId,
+                application_id: this.scope.applicationId,
+                contract_version: ARCHITECTURE_INVARIANT_CONTRACT_VERSION,
+                invariant_id: invariantId,
+                invariant_version: declared.version,
+                invariant_declaration_digest: declared.declaration_digest,
+                evaluator_id: requireText(input.evaluator, 'evaluator', 200),
+                evaluator: {
+                    id: requireText(input.evaluator, 'evaluator', 200),
+                    version: input.evaluatorVersion === undefined ? 'unspecified' : requireText(input.evaluatorVersion, 'evaluatorVersion', 200),
+                },
+                result,
+                evidence,
+                explanation,
+                findings,
+                ...(input.confidence === undefined ? {} : { confidence: input.confidence }),
+                evaluated_at: resolveEvaluatedAt(input.evaluatedAt, at),
+                recorded_at: timestamp(at),
+                provenance: this.provenance(decisionId, at),
+            };
+            await this.evaluationStore.create(FELTDB_ARCHITECTURE_EVALUATION_COLLECTION, key, row);
+            return toEvaluation(row);
+        },
+        get: async (evaluationId) => {
+            const id = requireIdentity(evaluationId, 'evaluationId');
+            await this.authorize(ARCHITECTURE_INVARIANT_CAPABILITIES.readEvaluation, FELTDB_ARCHITECTURE_EVALUATION_COLLECTION, id);
+            const row = await this.store.read(FELTDB_ARCHITECTURE_EVALUATION_COLLECTION, this.scopedKey(id));
+            if (!row || row.tenant_id !== this.scope.tenantId || row.application_id !== this.scope.applicationId) {
+                throw new FeltDBServiceError(`Evaluation ${id} was not found`, FeltDBErrorCode.NOT_FOUND);
+            }
+            return toEvaluation(row);
+        },
+        /** Page retained evaluations within this tenant and application. */
+        list: async (input = {}) => {
+            await this.authorize(ARCHITECTURE_INVARIANT_CAPABILITIES.readEvaluation, FELTDB_ARCHITECTURE_EVALUATION_COLLECTION, '*');
+            const where = [];
+            if (input.invariantId !== undefined)
+                where.push({ field: 'invariant_id', eq: requireIdentity(input.invariantId, 'invariantId') });
+            if (input.invariantVersion !== undefined) {
+                if (!Number.isInteger(input.invariantVersion) || input.invariantVersion < 1)
+                    throw invalid('invariantVersion must be a positive integer');
+                where.push({ field: 'invariant_version', eq: input.invariantVersion });
+            }
+            if (input.result !== undefined)
+                where.push({ field: 'result', eq: requireMember(input.result, ARCHITECTURE_EVALUATION_RESULTS, 'result') });
+            if (input.evaluator !== undefined)
+                where.push({ field: 'evaluator_id', eq: requireText(input.evaluator, 'evaluator', 200) });
+            const page = await this.store.query(this.scopedQuery(FELTDB_ARCHITECTURE_EVALUATION_COLLECTION, where, [{ field: 'recorded_at', direction: 'desc' }], boundedLimit(input.limit), input.cursor));
+            return {
+                evaluations: page.records.map(toEvaluation),
+                ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+                exhausted: page.exhausted,
+            };
+        },
+    };
+    /**
+     * Return the current declaration and its latest evaluation for each invariant.
+     *
+     * The invariant page is the snapshot boundary: history is never expanded and
+     * every evaluation lookup is limited to one record.
+     */
+    snapshot = async (input = {}) => {
+        const page = await this.invariants.list(input);
+        const entries = await Promise.all(page.invariants.map(async (invariant) => {
+            const evaluations = await this.evaluations.list({
+                invariantId: invariant.id,
+                invariantVersion: invariant.version,
+                limit: 1,
+            });
+            return {
+                invariant,
+                version: await this.invariants.version(invariant.id, invariant.version),
+                ...(evaluations.evaluations[0] ? { latestEvaluation: evaluations.evaluations[0] } : {}),
+            };
+        }));
+        return {
+            entries,
+            ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+            exhausted: page.exhausted,
+        };
+    };
+}
+/** Bind the durable architecture invariant substrate to a FeltDB instance. */
+export function createArchitectureInvariantService(db, options) {
+    return new FeltDBArchitectureInvariantService(createArchitectureInvariantStore(db), options);
+}