@feltdb/core 0.11.7 → 0.11.9

package/dist/composition.d.ts

@@ -0,0 +1,697 @@
+/**
+ * Authoritative composition: several applications over one `.flow`.
+ *
+ *                     authoritative .flow  (contract identity + digest)
+ *                              │
+ *                           FeltDB  ── the only authority for state
+ *                              │
+ *          ┌───────────────────┼───────────────────┐
+ *     consumer A          consumer B          consumer C
+ *     (declared access, capabilities, projections, connections)
+ *
+ * A consumer is an application, service, or agent that composes over the
+ * contract. It declares which collections it observes, mutates, or owns, and
+ * through which capability; FeltDB records that declaration durably and uses
+ * it as a ceiling. The authorization gate remains the authority for every
+ * individual operation, and it fails closed.
+ *
+ * Nothing here stores a copy of application state. Records stay in their
+ * contract collections. The substrate writes only `_feltdb.*` attribution,
+ * declaration, topology, observation, proposal, and impact records, and it
+ * writes them in the same atomic transaction as the state they describe.
+ *
+ * State-level proposals ("understand before mutate"):
+ *
+ *     intent (`_feltdb.Intent`, action=transition, target=state)
+ *        → proposal (`_feltdb.StateProposal`, bound to base snapshot N)
+ *        → impact  (`_feltdb.StateImpact`, computed from snapshot N)       ─ one transaction
+ *        → preview / review (`_feltdb.ProposalEvent`, the shared lifecycle)
+ *        → apply: CAS on base versions + topology fence + re-derived impact ─ one transaction
+ *
+ * FeltDB supplies facts, topology, authority, and provenance. What a change
+ * means is decided by the consumer, agent, or person reading them.
+ */
+import type { CanonicalApplicationContract } from './canonical-application.js';
+import type { AuthorizationDecision, AuthorizationRequest, AuthorizationSubject } from './authorization.js';
+import type { AuthorityQueryPage, AuthorityQueryRequest } from './http-db.js';
+import type { AtomicTransactionOptions, AtomicTransactionResult, AtomicTransactionScope, TransactionReadBasis, TransactionReadSet } from './transaction.js';
+import type { RuntimeSnapshotHandle, SnapshotDefinition, SnapshotIdentity, SnapshotBasis } from './runtime-snapshot.js';
+import type { IntentEvent, IntentStatus } from './intent.js';
+import type { FeltDBProposalEvent, ProposalStatus } from './proposal.js';
+import { type AuthoritativeContractIdentity, type CompositionAccess, type CompositionAccessMode, type CompositionProjection, type ImpactSurface, type ProposedOperation, type StateDependencyEdge, type StateRef } from './state-impact.js';
+export * from './state-impact.js';
+export declare const COMPOSITION_CONTRACT_VERSION = 1;
+export declare const COMPOSITION_MAX_LIMIT = 1000;
+/** Substrate capabilities, checked through the authorization gate. */
+export declare const COMPOSITION_CAPABILITIES: {
+    /** Record or re-record the authoritative contract identity. */
+    readonly bind: "composition:bind";
+    /** Admit a consumer's composition declaration. */
+    readonly declare: "composition:declare";
+    /** Act as a declared consumer. */
+    readonly act: "composition:act";
+    /** Approve or reject a state proposal. */
+    readonly review: "composition:review";
+};
+/** Every operation a consumer may be authorized for on one collection. */
+export declare const COMPOSITION_OPERATIONS: readonly ["read", "observe", "write", "delete"];
+export type CompositionOperation = typeof COMPOSITION_OPERATIONS[number];
+/**
+ * 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 declare const STATE_PROPOSAL_OPERATIONS: readonly [{
+    readonly operation: "intend";
+    readonly on: "consumer";
+    readonly method: "intend";
+    readonly authorization: readonly ["composition:act", "read on every proposed record"];
+    readonly writes: readonly ["_feltdb.Intent", "_feltdb.IntentEvent", "_feltdb.StateProposal", "_feltdb.StateImpact", "_feltdb.ProposalEvent"];
+}, {
+    readonly operation: "preview";
+    readonly on: "consumer";
+    readonly method: "preview";
+    readonly authorization: readonly ["composition:act", "read on every proposed record"];
+    readonly writes: readonly [];
+}, {
+    readonly operation: "history";
+    readonly on: "consumer";
+    readonly method: "history";
+    readonly authorization: readonly ["composition:act", "read on every proposed record"];
+    readonly writes: readonly [];
+}, {
+    readonly operation: "inspect";
+    readonly on: "review";
+    readonly method: "inspect";
+    readonly authorization: readonly ["composition:review"];
+    readonly writes: readonly [];
+}, {
+    readonly operation: "approve";
+    readonly on: "review";
+    readonly method: "approve";
+    readonly authorization: readonly ["composition:review"];
+    readonly writes: readonly ["_feltdb.StateProposal", "_feltdb.ProposalEvent"];
+}, {
+    readonly operation: "reject";
+    readonly on: "review";
+    readonly method: "reject";
+    readonly authorization: readonly ["composition:review"];
+    readonly writes: readonly ["_feltdb.StateProposal", "_feltdb.ProposalEvent"];
+}, {
+    readonly operation: "rebase";
+    readonly on: "consumer";
+    readonly method: "rebase";
+    readonly authorization: readonly ["composition:act", "read on every proposed record"];
+    readonly writes: readonly ["_feltdb.StateProposal", "_feltdb.StateImpact", "_feltdb.ProposalEvent", "_feltdb.Intent", "_feltdb.IntentEvent"];
+}, {
+    readonly operation: "apply";
+    readonly on: "consumer";
+    readonly method: "apply";
+    readonly authorization: readonly ["composition:act", "write (or delete, as owner) on every proposed record"];
+    readonly writes: readonly ["contract collections", "_feltdb.StateChange", "_feltdb.StateAttribution", "_feltdb.StateProposal", "_feltdb.ProposalEvent", "_feltdb.Intent", "_feltdb.IntentEvent"];
+}];
+/** Identity of a compiled contract. The digest is the contract's own hash, not a new one. */
+export declare function contractIdentity(contract: CanonicalApplicationContract): AuthoritativeContractIdentity;
+export interface CompositionProvenance {
+    subject: AuthorizationSubject;
+    tenant_id: string;
+    contract_id: string;
+    source: string;
+    recorded_at: string;
+    authorization_decision_ids: string[];
+}
+export interface CompositionDeclarationInput {
+    consumer: string;
+    access: CompositionAccess[];
+    projections?: CompositionProjection[];
+}
+export interface Composition {
+    consumer: string;
+    uri: string;
+    tenant_id: string;
+    contract_id: string;
+    contract_digest: string;
+    version: number;
+    digest: string;
+    status: 'active';
+    access: CompositionAccess[];
+    projections: CompositionProjection[];
+    /** The capabilities this composition names. Derived from `access`. */
+    requires: string[];
+    declared_at: string;
+    provenance: CompositionProvenance;
+}
+export interface StateRecord<T = Record<string, unknown>> {
+    uri: string;
+    ref: StateRef;
+    exists: boolean;
+    version: number | null;
+    value: T | null;
+}
+/** Durable attribution of one committed change. Carries no value: it cannot replay state. */
+export interface StateChange {
+    change_id: string;
+    tenant_id: string;
+    contract_id: string;
+    contract_digest: string;
+    subject: string;
+    collection: string;
+    record_id: string;
+    operation: 'insert' | 'update' | 'delete';
+    version_before: number | null;
+    version_after: number | null;
+    value_digest_before: string | null;
+    value_digest_after: string | null;
+    fields_changed: string[];
+    /** Version of the subject's attribution head this change produced. Authority-assigned. */
+    attribution_version: number;
+    transaction_id: string;
+    consumer: string;
+    capability: string;
+    causal_id?: string;
+    intent_id?: string;
+    proposal_id?: string;
+    impact_id?: string;
+    recorded_at: string;
+    provenance: CompositionProvenance;
+}
+export interface StateObservation {
+    observation_id: string;
+    tenant_id: string;
+    contract_id: string;
+    subject: string;
+    change_id?: string;
+    consumer: string;
+    observed_at: string;
+    recorded_at: string;
+    evidence: string[];
+    context: {
+        causal_id?: string;
+        parent_observation_id?: string;
+        correlation_id?: string;
+    };
+    provenance: CompositionProvenance;
+}
+export interface StateProposalOperation {
+    collection: string;
+    record_id: string;
+    subject: string;
+    operation: 'set' | 'delete';
+    value?: Record<string, unknown>;
+    base_version: number | null;
+    base_value_digest: string | null;
+}
+export interface StateSnapshotBinding {
+    id: string;
+    version: number | null;
+    scope?: string;
+    coherence: SnapshotBasis['coherence'];
+    derivation: SnapshotIdentity['derivation'];
+    /** Version of the contract's topology head in the snapshot; fences declarations and connections. */
+    topology_version: number | null;
+}
+/** A proposed state transition. Never authoritative until applied. */
+export interface StateProposal {
+    proposal_id: string;
+    intent_id: string;
+    tenant_id: string;
+    contract_id: string;
+    contract_digest: string;
+    status: ProposalStatus;
+    proposed_by: string;
+    summary: string;
+    operations: StateProposalOperation[];
+    proposal_digest: string;
+    base_snapshot: StateSnapshotBinding;
+    impact_id: string;
+    impact_digest: string;
+    parent_proposal_id?: string;
+    superseded_by?: string;
+    approval?: {
+        impact_id: string;
+        impact_digest: string;
+        approved_by: AuthorizationSubject;
+        decision_id: string;
+        approved_at: string;
+        note?: string;
+    };
+    rejection?: {
+        rejected_by: AuthorizationSubject;
+        decision_id?: string;
+        rejected_at: string;
+        reason: string;
+    };
+    applied?: {
+        transaction_id: string;
+        change_ids: string[];
+        applied_by: string;
+        applied_at: string;
+        apply_snapshot: StateSnapshotBinding;
+    };
+    authoritative: false;
+    created_at: string;
+    provenance: CompositionProvenance;
+}
+/** The impact surface of one proposal against its base snapshot. Written with the proposal. */
+export interface StateImpact {
+    impact_id: string;
+    proposal_id: string;
+    proposal_digest: string;
+    tenant_id: string;
+    contract_id: string;
+    contract_digest: string;
+    base_snapshot: StateSnapshotBinding;
+    surface: ImpactSurface;
+    surface_digest: string;
+    /**
+     * What the authority held, at the base snapshot, for exactly the state the
+     * surface was computed from. `apply` commits fenced by it: if any of that
+     * state has changed since — through any write path — the commit is refused.
+     */
+    read_basis: TransactionReadBasis;
+    computed_by: string;
+    computed_at: string;
+    /** An impact grants nothing: it describes, it never authorizes. */
+    grants_authority: false;
+    authoritative: false;
+    provenance: CompositionProvenance;
+}
+export type StateProposalBlocker = 'basis_changed' | 'contract_changed' | 'direct_state_changed' | 'impact_changed' | 'not_current_status';
+export interface StateProposalReadiness {
+    proposal_id: string;
+    status: ProposalStatus;
+    readiness: 'ready' | 'blocked';
+    blockers: StateProposalBlocker[];
+    /** True when the recorded impact no longer describes current authoritative state. */
+    stale: boolean;
+    base_snapshot: StateSnapshotBinding;
+    current_snapshot: StateSnapshotBinding;
+    /** The base snapshot is no longer the current one. Informational: unrelated writes do not block. */
+    basis_advanced: boolean;
+    /**
+     * Some declaration or connection in the contract changed since the base.
+     * Informational: only changes to the ones the impact read block, through
+     * `basis_changed` and `impact_changed`.
+     */
+    topology_advanced: boolean;
+    changed_subjects: string[];
+    current_impact_digest: string;
+}
+/** What a reader gets when it asks "what would change if this were applied?". */
+export interface StateProposalPreview {
+    proposal: StateProposal;
+    /**
+     * The impact, redacted to the reader. The read basis is withheld: it names
+     * every record the surface read, including ones this reader may not see, and
+     * it is the authority's fence, not the reader's information.
+     */
+    impact: Omit<StateImpact, 'surface' | 'read_basis'> & {
+        surface: ImpactSurface;
+        fenced: boolean;
+    };
+    readiness: StateProposalReadiness;
+    /** Evaluated for this reader, now. Not part of the durable impact. */
+    authorization: Array<{
+        node: string;
+        capability?: string;
+        operations: Record<'write' | 'delete', boolean>;
+    }>;
+    /** Nothing in this preview is authoritative state; only `apply` changes state. */
+    effect: {
+        authoritative: false;
+        state_changes_on: 'apply';
+    };
+}
+export interface CompositionAuthorizationGate {
+    check(request: AuthorizationRequest): Promise<AuthorizationDecision>;
+}
+/** The part of a FeltDB instance composition needs. Satisfied by `StateFirstDB`. */
+export interface CompositionDatabase {
+    collection<T>(name: string): {
+        get(id: string | number): Promise<T | null>;
+    };
+    query<T = Record<string, unknown>>(request: AuthorityQueryRequest): Promise<AuthorityQueryPage<T>>;
+    transaction(build: (tx: AtomicTransactionScope) => void | Promise<void>, options?: AtomicTransactionOptions): Promise<AtomicTransactionResult>;
+    snapshot<D = undefined>(definition: SnapshotDefinition<D>): RuntimeSnapshotHandle<D>;
+    readBasis(reads: TransactionReadSet): Promise<TransactionReadBasis>;
+}
+export interface AuthoritativeCompositionOptions {
+    contract: CanonicalApplicationContract;
+    tenantId: string;
+    /** Who acts through this handle. Every write is attributed to it. */
+    subject: AuthorizationSubject;
+    /** FeltDB's authorization boundary. Required: composition fails closed. */
+    authorization: CompositionAuthorizationGate;
+    /** What produced writes through this handle, e.g. an application name. */
+    source: string;
+    environment?: string;
+    /** Explicitly record a different contract digest as authoritative. */
+    rebind?: boolean;
+    now?: () => Date;
+}
+/**
+ * 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 declare function openAuthoritativeComposition(db: CompositionDatabase, options: AuthoritativeCompositionOptions): Promise<AuthoritativeComposition>;
+export declare class AuthoritativeComposition {
+    private readonly db;
+    readonly contract: AuthoritativeContractIdentity;
+    readonly tenantId: string;
+    readonly subject: AuthorizationSubject;
+    readonly environment: string;
+    private readonly gate;
+    private readonly source;
+    private readonly clock;
+    private readonly flowHash;
+    constructor(db: CompositionDatabase, options: AuthoritativeCompositionOptions);
+    private resource;
+    now(): string;
+    private normalizeDeclaration;
+    readonly 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: (input: CompositionDeclarationInput) => Promise<Composition>;
+        get: (consumer: string) => Promise<Composition>;
+        /** Page declared compositions over this contract. */
+        list: (input?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<{
+            exhausted: boolean;
+            nextCursor?: string | undefined;
+            items: Composition[];
+        }>;
+    };
+    /** Act as a declared consumer. The subject must be authorized to act as it. */
+    consumer(consumer: string): Promise<CompositionConsumer>;
+    readonly 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: (proposalId: string, input?: {
+            note?: string;
+        }) => Promise<StateProposal>;
+        reject: (proposalId: string, reason: string) => Promise<StateProposal>;
+        /** The full, unredacted proposal and impact, for an authorized reviewer. */
+        inspect: (proposalId: string) => Promise<{
+            proposal: StateProposal;
+            impact: StateImpact;
+            readiness: StateProposalReadiness;
+        }>;
+    };
+}
+export interface StateMutationBuilder {
+    set(collection: string, id: string, value: Record<string, unknown>): void;
+    delete(collection: string, id: string): void;
+}
+/**
+ * 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 declare class CompositionConsumer {
+    private readonly service;
+    private readonly db;
+    readonly composition: Composition;
+    constructor(service: AuthoritativeComposition, db: CompositionDatabase, composition: Composition);
+    get id(): string;
+    private get contractId();
+    private ref;
+    /** Refuse to act on a declaration that has been superseded since this handle was opened. */
+    private current;
+    private entry;
+    /** Declaration ceiling, then the gate. Returns the capability and the decision id. */
+    private access;
+    /** What this consumer is authorized to do, per declared collection, evaluated now. */
+    authorizedOperations(): Promise<Array<{
+        collection: string;
+        uri: string;
+        mode: CompositionAccessMode;
+        capability: string;
+        operations: Record<CompositionOperation, boolean>;
+    }>>;
+    private readable;
+    read<T = Record<string, unknown>>(collection: string, id: string): Promise<StateRecord<T>>;
+    query<T = Record<string, unknown>>(request: AuthorityQueryRequest): Promise<{
+        exhausted: boolean;
+        nextCursor?: string | undefined;
+        items: {
+            uri: string;
+            ref: StateRef;
+            exists: true;
+            version: number | null;
+            value: T;
+        }[];
+    }>;
+    /**
+     * 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.
+     */
+    mutate(build: (tx: StateMutationBuilder) => void, options?: {
+        causalId?: string;
+        transactionId?: string;
+    }): Promise<{
+        transaction: AtomicTransactionResult;
+        changes: StateChange[];
+    }>;
+    private commit;
+    /** Attributed changes to one collection (optionally one record), oldest first per record. */
+    changes(input: {
+        collection: string;
+        record?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        exhausted: boolean;
+        nextCursor?: string | undefined;
+        items: StateChange[];
+    }>;
+    private changeById;
+    /**
+     * Record that this consumer observed a subject, optionally a specific change.
+     *
+     * The schema is closed: there is no field for what the observation means.
+     */
+    observe(input: {
+        subject: string;
+        change?: string;
+        evidence?: string[];
+        context?: StateObservation['context'];
+        observedAt?: string;
+        observationId?: string;
+    }): Promise<StateObservation>;
+    observations(input: {
+        subject: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        exhausted: boolean;
+        nextCursor?: string | undefined;
+        items: StateObservation[];
+    }>;
+    /**
+     * 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.
+     */
+    connect(input: {
+        from: string;
+        to: string[];
+        evidence: string[];
+        label?: string;
+    }): Promise<StateDependencyEdge[]>;
+    /**
+     * 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.
+     */
+    projection(name: string): Promise<Readonly<{
+        uri: `projection://${string}/${string}/${string}`;
+        authoritative: false;
+        derived_from: string[];
+        identity: SnapshotIdentity;
+        get: <T = Record<string, unknown>>(collection: string, id: string) => T | undefined;
+        all: <T = Record<string, unknown>>(collection: string) => readonly T[];
+        staleness: () => Promise<import("./runtime-snapshot.js").SnapshotStaleness>;
+    }>>;
+    /**
+     * 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.
+     */
+    snapshot(input: {
+        collections: string[];
+    }): Promise<Readonly<{
+        contract: AuthoritativeContractIdentity;
+        consumer: string;
+        composition_version: number;
+        authorization: {
+            subject: AuthorizationSubject;
+            entries: {
+                collection: string;
+                capability: string;
+                decision_id: string;
+            }[];
+        };
+        identity: SnapshotIdentity;
+        coherence: "proven" | "unproven";
+        authoritative: false;
+        get: <T = Record<string, unknown>>(collection: string, id: string) => StateRecord<T>;
+        includes: (change: StateChange) => boolean;
+    }>>;
+    /** Everything this consumer may learn about the composed contract, for an agent or a person. */
+    describe(): Promise<{
+        contract: AuthoritativeContractIdentity;
+        self: Composition;
+        compositions: {
+            consumer: string;
+            uri: string;
+            version: number;
+            access: CompositionAccess[];
+            projections: CompositionProjection[];
+        }[];
+        compositions_exhausted: boolean;
+        authorized_operations: {
+            collection: string;
+            uri: string;
+            mode: CompositionAccessMode;
+            capability: string;
+            operations: Record<CompositionOperation, boolean>;
+        }[];
+    }>;
+    /**
+     * 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.
+     */
+    context(uri: string, input?: {
+        changes?: number;
+        observations?: number;
+    }): Promise<{
+        subject: StateRecord<Record<string, unknown>>;
+        basis: StateSnapshotBinding;
+        changes: StateChange[];
+        observations: StateObservation[];
+        connected: import("./state-impact.js").DependentImpact[];
+        unknown: import("./state-impact.js").UnknownImpact[];
+        authorized_operations: {
+            collection: string;
+            uri: string;
+            mode: CompositionAccessMode;
+            capability: string;
+            operations: Record<CompositionOperation, boolean>;
+        }[];
+    }>;
+    /** Validate the operations, read the basis, and compute the impact. Writes nothing. */
+    private prepareProposal;
+    /**
+     * "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.
+     */
+    intend(input: {
+        request: string;
+        summary?: string;
+        operations: ProposedOperation[];
+    }): Promise<StateProposalPreview>;
+    /**
+     * "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.
+     */
+    preview(proposalId: string): Promise<StateProposalPreview>;
+    /**
+     * 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`.
+     */
+    history(proposalId: string, input?: {
+        limit?: number;
+    }): Promise<{
+        proposal: StateProposal;
+        impact: Omit<StateImpact, "read_basis" | "surface"> & {
+            surface: ImpactSurface;
+            fenced: boolean;
+        };
+        readiness: StateProposalReadiness;
+        events: FeltDBProposalEvent[];
+        intent: {
+            id: string;
+            application_id: string;
+            environment: string;
+            raw_request: string;
+            action: "implement" | "extend" | "transition" | "unknown";
+            target: "module" | "billing" | "state" | "unknown";
+            module?: string;
+            module_version?: string;
+            parent_intent_id?: string;
+            contract_hash: string;
+            flow_hash: string;
+            status: IntentStatus;
+            ambiguities: import("./intent.js").IntentAmbiguity[];
+            created_at: string;
+            understanding?: import("./application-understanding.js").ApplicationUnderstanding;
+            plan?: import("./intent.js").ImplementationPlan;
+            proposal_id?: string;
+        } | null;
+        intent_events: IntentEvent[];
+        changes: StateChange[];
+        lineage: {
+            superseded_by?: string | undefined;
+            parent_proposal_id?: string | undefined;
+        };
+    }>;
+    /**
+     * 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.
+     */
+    rebase(proposalId: string): Promise<StateProposalPreview>;
+    /**
+     * 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.
+     */
+    apply(proposalId: string, options?: {
+        causalId?: string;
+    }): Promise<{
+        transaction: AtomicTransactionResult;
+        changes: StateChange[];
+    }>;
+    /**
+     * 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.
+     */
+    private recordRefusal;
+}
+//# sourceMappingURL=composition.d.ts.map