@feltdb/core 0.11.7 → 0.11.9

package/dist/runtime-snapshot.d.ts

@@ -132,6 +132,44 @@ export interface SnapshotStaleness {
     /** Why currency could not be decided. */
     reason?: string;
 }
+/**
+ * Which authoritative state a published snapshot represents, stated explicitly.
+ *
+ * Two snapshots with the same `id` represent the same durable state, derived
+ * by the same definition, under the same authority. The identity is computed
+ * from what the snapshot already is — its revision, definition, and authority
+ * — rather than stored as parallel metadata that could disagree with it.
+ */
+export interface SnapshotIdentity {
+    /** `snap_` + SHA-256 over the fields below. Deterministic across handles and processes. */
+    id: string;
+    name: string;
+    /**
+     * The authoritative revision value, when the runtime has one. `null` when it
+     * does not, in which case `contentDigest` identifies the state instead.
+     */
+    version: number | null;
+    /** The revision's consistency domain, when there is a revision. */
+    scope?: string;
+    /** Publication counter of the handle. Informational; not part of `id`. */
+    generation: number;
+    /** The source collections, sorted. */
+    sourceSet: readonly string[];
+    /** SHA-256 of the definition's sources, filters, and indexes. */
+    definitionDigest: string;
+    /** The authority the materialization read under (`tenant/…`, `platform`, or `unscoped`). */
+    authorityContext: string;
+    /**
+     * SHA-256 of the canonical materialized records. Present only when no
+     * authoritative revision exists, because then the content is the only honest
+     * identity there is.
+     */
+    contentDigest?: string;
+    /** How `id` was derived. */
+    derivation: 'revision' | 'content';
+    /** When materialization completed. Reporting only; not part of `id`. */
+    createdAt: number;
+}
 export interface SnapshotIndexDescription {
     collection: string;
     name: string;
@@ -175,6 +213,14 @@ export interface SnapshotHandleExplanation extends SnapshotExplanation {
      * claim.
      */
     durableReads: number;
+    /**
+     * `refresh()` calls answered by the fast path: the active snapshot already
+     * represented the current authoritative revision, so nothing was read or
+     * rebuilt.
+     */
+    reused: number;
+    /** The authority the handle materializes under. */
+    authorityContext: string;
 }
 export declare class SnapshotDefinitionError extends Error {
     constructor(message: string);
@@ -209,6 +255,11 @@ export interface RuntimeSnapshot<D = undefined> {
     /** Materialized records, across every source. */
     readonly records: number;
     readonly collections: readonly string[];
+    /**
+     * Which authoritative state this snapshot represents. Computed on first
+     * access and memoized, so the hot read path never pays for it.
+     */
+    readonly identity: SnapshotIdentity;
     get<T = Record<string, unknown>>(collection: string, id: string | number): T | undefined;
     has(collection: string, id: string | number): boolean;
     /** Every materialized record of one collection, in materialization order. Frozen. */
@@ -231,6 +282,17 @@ export interface RuntimeSnapshot<D = undefined> {
 export interface SnapshotSourceRuntime {
     /** Read every authoritative record of one collection. */
     readRecords(collection: string): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Read only the authoritative records that satisfy `where`, through the
+     * runtime's own bounded query (and its indexes, where it has them).
+     *
+     * Optional. When present it is the bounded source-selection fast path: a
+     * snapshot that selects ten records of a large collection reads ten records,
+     * not the collection. It must return exactly the records `readRecords` would
+     * after filtering by the same conditions — the build re-applies the filter
+     * regardless, so a runtime that over-returns cannot widen a snapshot.
+     */
+    readSelected?(collection: string, where: SnapshotCondition[]): Promise<Array<Record<string, unknown>>>;
     /** What freshness validation the underlying runtime can honestly support. */
     freshness(): Promise<FreshnessCapability>;
     /** The runtime's current revision. Called only when freshness advertises one. */
@@ -254,7 +316,10 @@ export declare class RuntimeSnapshotHandle<D = undefined> {
     private durableReads;
     private lastFailure?;
     private closed;
-    constructor(definition: SnapshotDefinition<D>, source: SnapshotSourceRuntime);
+    private reused;
+    private readonly definitionDigest;
+    readonly authorityContext: string;
+    constructor(definition: SnapshotDefinition<D>, source: SnapshotSourceRuntime, options?: RuntimeSnapshotOptions);
     get name(): string;
     /**
      * The active snapshot, or `undefined` before the first successful build.
@@ -325,7 +390,16 @@ export declare function assertSnapshotDefinition(definition: SnapshotDefinition<
  * `StateFirstDB.snapshot()` is the application-facing form; this is the same
  * primitive for runtimes and tools that hold a source of their own.
  */
-export declare function createRuntimeSnapshot<D = undefined>(definition: SnapshotDefinition<D>, source: SnapshotSourceRuntime): RuntimeSnapshotHandle<D>;
+export declare function createRuntimeSnapshot<D = undefined>(definition: SnapshotDefinition<D>, source: SnapshotSourceRuntime, options?: RuntimeSnapshotOptions): RuntimeSnapshotHandle<D>;
+export interface RuntimeSnapshotOptions {
+    /**
+     * The authority the source reads under. `db.snapshot()` supplies the
+     * database's own authority scope; the source it hands the handle is already
+     * bound to that scope, so a snapshot can never read more than its database
+     * could. Recorded in every snapshot's identity.
+     */
+    authorityContext?: string;
+}
 /**
  * Whether two definitions describe the same snapshot.
  *

package/dist/runtime-snapshot.d.ts.map

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

package/dist/runtime-snapshot.js

@@ -30,6 +30,7 @@
  */
 import { isCacheCurrent, } from './freshness.js';
 import { conditionMatches, EmbeddedQueryEngine } from './embedded-query.js';
+import { canonicalJson, sha256Hex } from './stable-hash.js';
 export class SnapshotDefinitionError extends Error {
     constructor(message) { super(message); this.name = 'SnapshotDefinitionError'; }
 }
@@ -56,17 +57,57 @@ class PublishedSnapshot {
     generation;
     basis;
     materialization;
+    definitionDigest;
+    authorityContext;
     collections;
     records;
-    constructor(name, generation, basis, materialization) {
+    // Memo cell, not snapshot state: identity is a pure function of what is
+    // already frozen, computed once on first access.
+    memo = {};
+    constructor(name, generation, basis, materialization, definitionDigest, authorityContext) {
         this.name = name;
         this.generation = generation;
         this.basis = basis;
         this.materialization = materialization;
+        this.definitionDigest = definitionDigest;
+        this.authorityContext = authorityContext;
         this.collections = Object.freeze([...materialization.byCollection.keys()]);
         this.records = materialization.records.size;
         Object.freeze(this);
     }
+    get identity() {
+        if (this.memo.identity)
+            return this.memo.identity;
+        const sourceSet = Object.freeze([...this.collections].sort());
+        const revision = this.basis.validation === 'revision' ? this.basis.revision : undefined;
+        const contentDigest = revision ? undefined : sha256Hex(canonicalJson(sourceSet.map(collection => [
+            collection,
+            [...(this.materialization.byCollection.get(collection) ?? EMPTY)]
+                .map(record => canonicalJson(record))
+                .sort(),
+        ])));
+        const id = `snap_${sha256Hex(canonicalJson([
+            'feltdb.snapshot.v1',
+            this.name,
+            this.definitionDigest,
+            this.authorityContext,
+            revision ? ['revision', revision.scope, revision.value] : ['content', contentDigest],
+        ]))}`;
+        this.memo.identity = Object.freeze({
+            id,
+            name: this.name,
+            version: revision ? revision.value : null,
+            ...(revision ? { scope: revision.scope } : {}),
+            generation: this.generation,
+            sourceSet,
+            definitionDigest: this.definitionDigest,
+            authorityContext: this.authorityContext,
+            ...(contentDigest ? { contentDigest } : {}),
+            derivation: revision ? 'revision' : 'content',
+            createdAt: this.basis.materializedAt,
+        });
+        return this.memo.identity;
+    }
     get revision() { return this.basis.revision; }
     get materializedAt() { return this.basis.materializedAt; }
     get(collection, id) {
@@ -129,10 +170,15 @@ export class RuntimeSnapshotHandle {
     durableReads = 0;
     lastFailure;
     closed = false;
-    constructor(definition, source) {
+    reused = 0;
+    definitionDigest;
+    authorityContext;
+    constructor(definition, source, options = {}) {
         this.definition = definition;
         this.source = source;
         assertSnapshotDefinition(definition);
+        this.definitionDigest = sha256Hex(definitionShape(definition));
+        this.authorityContext = options.authorityContext ?? 'unscoped';
     }
     get name() { return this.definition.name; }
     /**
@@ -162,8 +208,10 @@ export class RuntimeSnapshotHandle {
         this.assertOpen();
         if (!options.force && this.active) {
             const staleness = await this.staleness();
-            if (staleness.state === 'current')
+            if (staleness.state === 'current') {
+                this.reused += 1;
                 return this.active;
+            }
         }
         return this.build();
     }
@@ -240,6 +288,8 @@ export class RuntimeSnapshotHandle {
             failures: this.failures,
             ...(this.lastFailure ? { lastFailure: this.lastFailure } : {}),
             durableReads: this.durableReads,
+            reused: this.reused,
+            authorityContext: this.authorityContext,
         };
     }
     /**
@@ -322,7 +372,9 @@ export class RuntimeSnapshotHandle {
         const indexes = [];
         for (const source of this.definition.sources) {
             this.durableReads += 1;
-            const durable = await this.source.readRecords(source.collection);
+            const durable = source.where?.length && this.source.readSelected
+                ? await this.source.readSelected(source.collection, source.where)
+                : await this.source.readRecords(source.collection);
             const kept = [];
             for (const record of durable) {
                 if (!record || typeof record !== 'object' || Array.isArray(record))
@@ -389,7 +441,7 @@ export class RuntimeSnapshotHandle {
      * visible.
      */
     publish(materialization, basis) {
-        const candidate = new PublishedSnapshot(this.name, this.generation + 1, Object.freeze(basis), materialization);
+        const candidate = new PublishedSnapshot(this.name, this.generation + 1, Object.freeze(basis), materialization, this.definitionDigest, this.authorityContext);
         this.definition.validate?.(candidate);
         this.active = candidate;
         this.generation = candidate.generation;
@@ -455,8 +507,17 @@ export function assertSnapshotDefinition(definition) {
  * `StateFirstDB.snapshot()` is the application-facing form; this is the same
  * primitive for runtimes and tools that hold a source of their own.
  */
-export function createRuntimeSnapshot(definition, source) {
-    return new RuntimeSnapshotHandle(definition, source);
+export function createRuntimeSnapshot(definition, source, options = {}) {
+    return new RuntimeSnapshotHandle(definition, source, options);
+}
+/** The identity-bearing shape of a definition: sources, filters, and indexes. */
+function definitionShape(definition) {
+    return canonicalJson({
+        name: definition.name,
+        sources: [...definition.sources]
+            .map(source => ({ collection: source.collection, where: source.where ?? [], indexes: source.indexes ?? [] }))
+            .sort((left, right) => (left.collection < right.collection ? -1 : left.collection > right.collection ? 1 : 0)),
+    });
 }
 /**
  * Whether two definitions describe the same snapshot.

package/dist/stable-hash.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Synchronous, dependency-free SHA-256 and canonical JSON.
+ *
+ * Snapshot identity must be computable in every runtime `@feltdb/core` ships
+ * to — Node, browsers, workers — and synchronously, because a published
+ * snapshot answers without awaiting anything. WebCrypto is asynchronous and
+ * `node:crypto` is not available in a browser, so this is the small portable
+ * implementation both need. It is used for identity, not for security.
+ */
+/** SHA-256 of a UTF-8 string, as lowercase hex. */
+export declare function sha256Hex(input: string): string;
+/**
+ * JSON with object keys sorted at every depth, so two structurally equal
+ * values serialize to the same bytes regardless of insertion order.
+ */
+export declare function canonicalJson(value: unknown): string;
+//# sourceMappingURL=stable-hash.d.ts.map

package/dist/stable-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stable-hash.d.ts","sourceRoot":"","sources":["../src/stable-hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH,mDAAmD;AACnD,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CA+B/C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAUpD"}

package/dist/stable-hash.js

@@ -0,0 +1,82 @@
+/**
+ * Synchronous, dependency-free SHA-256 and canonical JSON.
+ *
+ * Snapshot identity must be computable in every runtime `@feltdb/core` ships
+ * to — Node, browsers, workers — and synchronously, because a published
+ * snapshot answers without awaiting anything. WebCrypto is asynchronous and
+ * `node:crypto` is not available in a browser, so this is the small portable
+ * implementation both need. It is used for identity, not for security.
+ */
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+/** SHA-256 of a UTF-8 string, as lowercase hex. */
+export function sha256Hex(input) {
+    const bytes = new TextEncoder().encode(input);
+    const bitLength = bytes.length * 8;
+    const padded = new Uint8Array(((bytes.length + 9 + 63) >> 6) << 6);
+    padded.set(bytes);
+    padded[bytes.length] = 0x80;
+    const view = new DataView(padded.buffer);
+    view.setUint32(padded.length - 8, Math.floor(bitLength / 0x100000000));
+    view.setUint32(padded.length - 4, bitLength >>> 0);
+    const h = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
+    const w = new Uint32Array(64);
+    for (let offset = 0; offset < padded.length; offset += 64) {
+        for (let i = 0; i < 16; i += 1)
+            w[i] = view.getUint32(offset + i * 4);
+        for (let i = 16; i < 64; i += 1) {
+            const a = w[i - 15], b = w[i - 2];
+            const s0 = ((a >>> 7) | (a << 25)) ^ ((a >>> 18) | (a << 14)) ^ (a >>> 3);
+            const s1 = ((b >>> 17) | (b << 15)) ^ ((b >>> 19) | (b << 13)) ^ (b >>> 10);
+            w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+        }
+        let [a, b, c, d, e, f, g, hh] = h;
+        for (let i = 0; i < 64; i += 1) {
+            const s1 = ((e >>> 6) | (e << 26)) ^ ((e >>> 11) | (e << 21)) ^ ((e >>> 25) | (e << 7));
+            const t1 = (hh + s1 + ((e & f) ^ (~e & g)) + K[i] + w[i]) >>> 0;
+            const s0 = ((a >>> 2) | (a << 30)) ^ ((a >>> 13) | (a << 19)) ^ ((a >>> 22) | (a << 10));
+            const t2 = (s0 + ((a & b) ^ (a & c) ^ (b & c))) >>> 0;
+            hh = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        h[0] += a;
+        h[1] += b;
+        h[2] += c;
+        h[3] += d;
+        h[4] += e;
+        h[5] += f;
+        h[6] += g;
+        h[7] += hh;
+    }
+    return Array.from(h, word => word.toString(16).padStart(8, '0')).join('');
+}
+/**
+ * JSON with object keys sorted at every depth, so two structurally equal
+ * values serialize to the same bytes regardless of insertion order.
+ */
+export function canonicalJson(value) {
+    if (value === null || typeof value !== 'object') {
+        return value === undefined ? 'null' : JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    const entries = Object.keys(value)
+        .filter(key => value[key] !== undefined)
+        .sort()
+        .map(key => `${JSON.stringify(key)}:${canonicalJson(value[key])}`);
+    return `{${entries.join(',')}}`;
+}

package/dist/state-impact.d.ts

@@ -0,0 +1,245 @@
+/** Collections the composition substrate writes. Never contract state. */
+export declare const FELTDB_COMPOSITION_CONTRACT_COLLECTION = "_feltdb.CompositionContract";
+export declare const FELTDB_COMPOSITION_COLLECTION = "_feltdb.Composition";
+export declare const FELTDB_COMPOSITION_VERSION_COLLECTION = "_feltdb.CompositionVersion";
+export declare const FELTDB_COMPOSITION_TOPOLOGY_COLLECTION = "_feltdb.CompositionTopology";
+export declare const FELTDB_STATE_OWNERSHIP_COLLECTION = "_feltdb.StateOwnership";
+export declare const FELTDB_STATE_DEPENDENCY_COLLECTION = "_feltdb.StateDependency";
+export declare const FELTDB_STATE_CHANGE_COLLECTION = "_feltdb.StateChange";
+export declare const FELTDB_STATE_ATTRIBUTION_COLLECTION = "_feltdb.StateAttribution";
+export declare const FELTDB_STATE_OBSERVATION_COLLECTION = "_feltdb.StateObservation";
+export declare const FELTDB_STATE_PROPOSAL_COLLECTION = "_feltdb.StateProposal";
+export declare const FELTDB_STATE_IMPACT_COLLECTION = "_feltdb.StateImpact";
+/** Upper bound on `connects` hops followed from a directly changed record. */
+export declare const IMPACT_MAX_DEPTH = 4;
+/** Upper bound on items in any one section of a surface. */
+export declare const IMPACT_MAX_ITEMS = 1000;
+/**
+ * The identity of an authoritative `.flow` contract.
+ *
+ * State is addressed by contract, collection, and record — never by the
+ * application that happens to be looking at it — so the same record has the
+ * same identity for every consumer.
+ */
+export interface AuthoritativeContractIdentity {
+    contract_id: string;
+    /** Digest of the whole compiled contract (`CanonicalApplicationContract.hashes.application`). */
+    contract_digest: string;
+    /** Digest of collections, indexes, and references (`hashes.model`). */
+    model_digest: string;
+    collections: string[];
+    capabilities: string[];
+    /** Declared field types, by collection. */
+    fields: Record<string, Array<{
+        name: string;
+        type: string;
+        reference?: string;
+    }>>;
+    /** Declared workflows and the capabilities their steps name. */
+    workflows: Array<{
+        name: string;
+        capabilities: string[];
+    }>;
+    /** Declared triggers: an event that starts a workflow. `workflow` is `''` when the trigger names none. */
+    triggers: Array<{
+        name: string;
+        event: string;
+        workflow: string;
+    }>;
+}
+/** Address of authoritative state. `record` absent means the whole collection. */
+export interface StateRef {
+    contract: string;
+    collection: string;
+    record?: string;
+}
+export declare function stateUri(ref: StateRef): string;
+export declare function parseStateUri(uri: string): StateRef;
+export declare const consumerUri: (contract: string, consumer: string) => string;
+export declare const capabilityUri: (contract: string, capability: string) => string;
+export declare const projectionUri: (contract: string, consumer: string, name: string) => string;
+export declare const workflowUri: (contract: string, workflow: string) => string;
+/** `sha256:` over FeltDB's canonical encoding. */
+export declare function canonicalDigest(value: unknown): Promise<string>;
+/** Record fields the storage boundary owns. They are not part of a value. */
+export declare function recordValue(row: Record<string, unknown> | null | undefined): Record<string, unknown> | null;
+export declare function recordVersion(row: Record<string, unknown> | null | undefined): number | null;
+export declare function changedFields(before: Record<string, unknown> | null, after: Record<string, unknown> | null): string[];
+export type CompositionAccessMode = 'observe' | 'mutate' | 'own';
+export interface CompositionAccess {
+    collection: string;
+    mode: CompositionAccessMode;
+    capability: string;
+}
+export interface CompositionProjection {
+    name: string;
+    sources: string[];
+}
+/** The part of a composition declaration the impact surface depends on. */
+export interface CompositionTopologyEntry {
+    consumer: string;
+    version: number;
+    status: 'active';
+    access: CompositionAccess[];
+    projections: CompositionProjection[];
+}
+/** An explicit, consumer-declared connection between two records. */
+export interface StateDependencyEdge {
+    edge_id: string;
+    from: string;
+    to: string;
+    relationship: 'connects';
+    declared_by: string;
+    label?: string;
+    evidence: string[];
+}
+export type ProposedOperation = {
+    collection: string;
+    id: string;
+    value: Record<string, unknown>;
+} | {
+    collection: string;
+    id: string;
+    delete: true;
+};
+/** Why an item is in the surface. Every item carries one. */
+export interface ImpactProvenance {
+    basis: 'proposal' | 'declared_dependency' | 'composition_declaration' | 'contract_reference' | 'contract_trigger' | 'contract_model';
+    /** The durable thing the item was derived from, as `scheme:reference`. */
+    source: string;
+    evidence: string[];
+}
+export interface DirectImpact {
+    node: string;
+    collection: string;
+    record_id: string;
+    operation: 'insert' | 'update' | 'delete';
+    base_version: number | null;
+    proposed_version: number | null;
+    base_value_digest: string | null;
+    proposed_value_digest: string | null;
+    fields_changed: string[];
+    provenance: ImpactProvenance;
+}
+export interface DependentImpact {
+    node: string;
+    kind: 'state' | 'consumer' | 'projection' | 'workflow';
+    /** The structural relationship, never an interpretation of it. */
+    relationship: string;
+    /** The node this one was reached from. */
+    from: string;
+    /** `connects` hops from the nearest directly changed record. */
+    depth: number;
+    capability?: string;
+    declared_by?: string;
+    label?: string;
+    /** For a workflow: the trigger and event that make it reachable, and the capabilities its steps name. */
+    trigger?: string;
+    event?: string;
+    capabilities?: string[];
+    provenance: ImpactProvenance;
+}
+export interface DerivedImpact {
+    node: string;
+    consequence: 'record_version_advances' | 'record_removed' | 'record_created' | 'reference_retargeted' | 'reference_target_absent' | 'reference_to_removed_record' | 'projection_source_changes';
+    field?: string;
+    before?: unknown;
+    after?: unknown;
+    provenance: ImpactProvenance;
+}
+export interface UnknownImpact {
+    kind: 'unregistered_consumers' | 'opaque_field' | 'workflow_effects' | 'unattributed_history' | 'traversal_bound' | 'external_reference' | 'unresolved_workflow' | 'unrecognized_trigger_event' | 'external_trigger_events' | 'not_authorized_to_inspect';
+    node?: string;
+    event?: string;
+    collection?: string;
+    field?: string;
+    count?: number;
+    /** Why this cannot be established from the authoritative model. */
+    reason: string;
+}
+export interface ImpactSurface {
+    direct: DirectImpact[];
+    dependent: DependentImpact[];
+    derived: DerivedImpact[];
+    /**
+     * Never empty. FeltDB cannot enumerate consumers that never declared a
+     * composition, so the surface is always open, and says so.
+     */
+    unknown: UnknownImpact[];
+}
+/** Read access to the materialized basis. Satisfied by `RuntimeSnapshot`. */
+export interface ImpactBasis {
+    get<T = Record<string, unknown>>(collection: string, id: string | number): T | undefined;
+    all<T = Record<string, unknown>>(collection: string): readonly T[];
+    readonly collections: readonly string[];
+}
+/**
+ * What a surface computation read, as a transaction read set.
+ *
+ * `records` are point reads; `predicates` are equality reads ("every record of
+ * `collection` whose fields equal these values"). The surface is a function of
+ * exactly these reads, so a transaction fenced on them (`db.readBasis()` +
+ * `tx.fence()`) cannot commit against a state in which the surface differs.
+ */
+export interface ImpactReads {
+    records: Map<string, {
+        collection: string;
+        id: string;
+    }>;
+    predicates: Map<string, {
+        collection: string;
+        where: Array<{
+            field: string;
+            eq: unknown;
+        }>;
+    }>;
+}
+export declare function emptyImpactReads(): ImpactReads;
+/** The reads as a `TransactionReadSet`. */
+export declare function impactReadSet(reads: ImpactReads): {
+    records: Array<{
+        collection: string;
+        id: string;
+    }>;
+    predicates: Array<{
+        collection: string;
+        where: Array<{
+            field: string;
+            eq: unknown;
+        }>;
+    }>;
+};
+export interface ImpactInput {
+    contract: AuthoritativeContractIdentity;
+    tenantId: string;
+    basis: ImpactBasis;
+    operations: readonly ProposedOperation[];
+    maxDepth?: number;
+    /** Filled with what the computation read. Does not affect the surface. */
+    reads?: ImpactReads;
+}
+/** The transition events a contract trigger can name for a collection. */
+export declare const TRANSITION_EVENTS: {
+    readonly insert: "created";
+    readonly update: "updated";
+    readonly delete: "deleted";
+};
+/**
+ * Compute the impact surface of `operations` against `basis`.
+ *
+ * Pure and deterministic. The output is sorted so that its canonical digest is
+ * a function of the snapshot and the operations alone.
+ */
+export declare function computeImpactSurface(input: ImpactInput): Promise<ImpactSurface>;
+/** Canonical digest of a surface, for comparing an analysis with a re-derivation. */
+export declare function impactSurfaceDigest(surface: ImpactSurface): Promise<string>;
+/**
+ * The part of a surface a reader may see.
+ *
+ * The surface is computed by the authority over all state, so that its digest
+ * does not depend on who asked. A reader sees state nodes only in collections
+ * it may read; everything withheld is counted under `unknown` rather than
+ * silently dropped, because "you may not see it" is not "it is not there".
+ */
+export declare function redactImpactSurface(surface: ImpactSurface, readable: (collection: string) => boolean): ImpactSurface;
+//# sourceMappingURL=state-impact.d.ts.map

package/dist/state-impact.d.ts.map

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