@cruba/crubal 0.1.0 → 0.2.0

package/dist/src/exchange.d.ts

@@ -1,5 +1,11 @@
+import type { Access } from "./access.ts";
+import { type Arrival } from "./arrival.ts";
+import type { Journal } from "./log.ts";
+import type { Views } from "./views.ts";
 import type { Dictionary } from "./defs.ts";
 import type { Json, JsonObject, Record } from "./model.ts";
+import { type RecordSet } from "./records.ts";
+import { Engine, type Rule } from "./rules.ts";
 import { type Contract, type Keys } from "./store.ts";
 export type Role = {
     name: string;
@@ -10,8 +16,8 @@ export type Role = {
     line: number;
 };
 export declare function readRoles(source: string): Role[];
-/** Check contracts against a dictionary (7.10). Throws the first problem. */
-export declare function checkContracts(contracts: Contract[], dict: Dictionary, ownPrefix?: string): void;
+/** Check contracts against a dictionary (7.10). Throws the first problem. `views` lets stream contracts be checked. */
+export declare function checkContracts(contracts: Contract[], dict: Dictionary, ownPrefix?: string, views?: Set<string>): void;
 export type RunResult = {
     [k: string]: Json;
 };
@@ -19,10 +25,82 @@ export declare class Exchange {
     readonly dict: Dictionary;
     readonly contracts: Map<string, Contract>;
     readonly roles: Role[];
-    private records;
-    private sent;
-    private runs;
-    constructor(dict: Dictionary, contracts: Contract[], roles?: Role[]);
+    /** The records, shared with the Access that decides over them (chapter 14). */
+    records: RecordSet;
+    bindings: Map<string, string>;
+    /** Set to make the border consult access: `run` needs the caller's `run` item, gated access suggests. */
+    access?: Access;
+    /**
+     * How an arrival's new record is named (9.2a). A persistent store sets this to mint the next id of the
+     * owner (`P-2` after `P-1`), since an Exchange is built per run and its own counter would start again.
+     * Without it the memory border's `<L>-NEW<n>` stands.
+     */
+    mint?: (level: string) => string;
+    /** Set to make every run a transaction (8.5): the border works on the journal's draft and commits each run. */
+    journal?: Journal;
+    /** Set to let stream contracts (12.6.2) carry the views' projection streams. */
+    views?: Views;
+    /** Per stream contract, the cursor each view's index has acknowledged, with the version it was for. */
+    private cursors;
+    /** The rules a run's step 6 applies (7.4): the package's, plus the facet shortcuts the engine adds. */
+    readonly engine: Engine;
+    /** Idempotency keys acted on (7.5); a store that outlives the instance seeds and keeps them. */
+    readonly sent: Set<string>;
+    /** Runs so far, which numbers the next run's log; a store continues the count across instances. */
+    runs: number;
+    /** Records minted by arrivals (9.2a), likewise. */
+    minted: number;
+    /** The versions a run uses (7.4 step 7, 8.5): the package's, set by a store; the contract's is added per run. */
+    versions: JsonObject;
+    /** The review queue the border writes to (a dead run, an answer naming no run); the journal's draft list. */
+    review: JsonObject[];
+    /** Observations this instance made (9.7); a store keeps every one in its state. */
+    observations: JsonObject[];
+    private observed;
+    /** The package's thresholds (11.1): instances to propose a version split, witnesses to confirm. */
+    thresholds: {
+        confirm?: number;
+        split?: number;
+    };
+    /** Review items already open in the store, for a border that loads them apart from the draft's list. */
+    knownReview: JsonObject[];
+    /** Mapped-out payloads kept beside the log, by run (docs/design/runs.md): a store keeps them in outtake. */
+    readonly outtake: Map<string, JsonObject>;
+    /** Runs the store knows beyond this instance's entries (a border over a store seeds them): run → contract and record. */
+    readonly runsKnown: Map<string, {
+        contract: string;
+        record: string;
+    }>;
+    /** Runs started and not yet acted or failed, by run: what a restarted host asks the adapter about. */
+    readonly started: Map<string, {
+        contract: string;
+        record: string;
+        key: string;
+        attempts: number;
+        cause?: string;
+    }>;
+    constructor(dict: Dictionary, contracts: Contract[], roles?: Role[], rules?: Rule[]);
+    /**
+     * Step 6 of a run (7.4): what came in runs through the rules (chapter 6). A `must` the write breaks
+     * refuses it and nothing changes; a hold takes the value out of the current values; a fill or derivation
+     * lands with `origin: derived` and the rule as its `via`. Returns the record to keep, or the refusal.
+     */
+    private applyRules;
+    /** Run the ancestors' productions again after a write below them; the ids whose values changed. */
+    reproduceAncestors(id: string): string[];
+    /** Work on a journal's draft, so every run the border makes is one logged entry (8.5). */
+    useJournal(journal: Journal): void;
+    /** Log a run's transaction: what it changed on the draft, the run's own state, and any observations (8.5). */
+    private commit;
+    /** Step 1 of a run (7.4): the menu is the permission (14.6); `who` only narrows. */
+    private permitted;
+    /** The gated edge a caller's access comes through, if every granting edge is gated (14.7). */
+    private gate;
+    /**
+     * A contract that creates a record for a caller grants their edge on it (14.4): `mode: consume`, the
+     * contract's `relation`, under the owner's grant.
+     */
+    private grantConsumer;
     put(r: Record): void;
     get(id: string): Record | undefined;
     /** A record's values with everything above it read through (1.7). */
@@ -30,14 +108,127 @@ export declare class Exchange {
     /** The value an address names from a record, with a level prefix reading that level. */
     private read;
     private nextLog;
-    /** Steps 1–4 of a send (or form) contract: permission, needs, map out, act once. */
+    /**
+     * A send (or form) contract's run with no act between (the memory border, docs/design/runs.md): prepare,
+     * then acted, in two entries. A host puts its adapter between `prepare` and `acted` or `failed`.
+     */
     run(name: string, recordId: string, callerId?: string): RunResult;
+    /**
+     * Steps 1–3 of a send (7.4): permission, needs, map out; then the run is `started`, its idempotency key
+     * and the payload's hash logged, the payload itself kept beside the log. A key already started or acted
+     * is never sent again (7.5).
+     */
+    prepare(name: string, recordId: string, callerId?: string, cause?: string): RunResult;
+    /** The act succeeded: the run is `acted` (docs/design/runs.md). */
+    acted(run: string, at?: string): RunResult;
+    /** How many attempts a contract allows (7.5 `retry: N every D`): one without it. */
+    private attemptsAllowed;
+    /**
+     * The act failed: a `failed` entry with the attempt; after the last attempt the contract allows, a
+     * review item `run:<contract>` opens, grouped by contract across records, and the run stays failed.
+     */
+    failed(run: string, reason: string): RunResult;
+    /**
+     * A decision on a dead run (runs.md): `retry` releases its key and starts a new run from the record as it
+     * now is; `drop` closes the item. Either is a review write.
+     */
+    decideRun(run: string, decision: "retry" | "drop", callerId?: string): RunResult;
+    /** Run the contract that reverses a run (7.5 `undo`): an ordinary send naming its cause. */
+    /** The contract and record of a run this instance or its store knows. */
+    runOf(run: string): {
+        contract: string;
+        record: string;
+    } | undefined;
+    undo(run: string, callerId?: string): RunResult;
     private needsOf;
-    /** Steps 5–6 for a receive contract: map the answer back, compare with the record, and land it. */
-    receiveRun(name: string, recordId: string, body: string): RunResult;
-    /** Offer and take (7.8): only what the offer gives and the take reads flows. */
-    take(takeName: string, offerName: string, recordId: string, presenter: Record): RunResult;
+    /**
+     * Steps 5–6 for a receive contract: map the answer back, compare with the record, and land it. Under a
+     * gated edge (14.7) the values land as suggestions for the edge's reviewer, whatever the contract says.
+     */
+    receiveRun(name: string, recordId: string, body: string, callerId?: string, forRun?: string): RunResult;
+    /**
+     * An arrival through a contract (9.2a): the payload finds or makes its record; a new record made for a
+     * caller gets their consumer edge (14.4).
+     */
+    arriveRun(name: string, body: string, level: string, callerId?: string, of?: string, within?: string): RunResult;
+    /** The arrival type, re-exported for callers that read `arrival`. */
+    static arrivalOf(r: RunResult): Arrival | undefined;
+    /**
+     * A stream contract's run (12.6.2): the entries of each view since the cursor, in order. Pushed (the
+     * stored cursor, acknowledged by the index) or pulled (the caller's cursor). A view above `public` goes
+     * only to a party holding `run` for the contract.
+     */
+    streamRun(name: string, callerId?: string, cursor?: {
+        [view: string]: number;
+    }): RunResult;
+    private lastTick;
+    /**
+     * A scheduled contract's tick (7.11): the host offers its clock as `now`; every tick due since the last
+     * one runs (or only the latest, or none, by `missed`), each run keyed by the contract and the tick so a
+     * restarted host never runs a tick twice. A send contract with `for` runs over every record it selects;
+     * a stream contract pushes; any other runs once with no record.
+     */
+    tick(name: string, now: string, callerId?: string): RunResult;
+    /** The index acknowledges what it holds: the store resumes from there (12.6.2). */
+    ack(name: string, cursor: {
+        [view: string]: number;
+    }): RunResult;
+    /** The classes a record wears, those of the records above it included (5.5). */
+    private wearsOf;
+    /**
+     * An offer (7.8): the records the contract's `for` selects, with only the facets it gives, each value with
+     * its source; the mode and terms ride along. A value the owner took under `reshare: no` never flows on.
+     * Who may see it is the host's decision from `to`.
+     */
+    offer(name: string, owner: string, only?: string[]): Offer;
+    /**
+     * Offer and take (7.8): only what the offer gives and the take reads flows, by the offer's mode.
+     * `dump` copies once and never updates; `observed` stores a link and no value; `gathered` copies and
+     * takes the presenter's updates as intake, never over a value the consumer entered; `controlled` copies
+     * under the presenter's terms, which do override, expire and withdraw. The entry names the presenter's
+     * entry the values came from (8.5.1).
+     */
+    take(takeName: string, offer: string | Offer, recordId: string, presenter: Record): RunResult;
+    /** A local offer contract as an offer object, for a take run against a presenter record at hand. */
+    private localOffer;
+    /** Taken values past their terms' `expires` (7.8) are removed, each record one entry; the ids changed. */
+    expire(now: string): string[];
 }
+/** An offer as one owner's host serves it to another (7.8): the border wrapper's content. */
+export type Offer = {
+    contract: string;
+    owner: string;
+    to: string;
+    mode: string;
+    terms: {
+        [term: string]: string;
+    };
+    gives: string[];
+    records: Record[];
+    log?: JsonObject[]; /** The package version the records were written under (3.8, 10.1): `<owner>/<name> /<version>`. */
+    package?: string;
+};
+/**
+ * The version gate at a border (10.1): what a receiver does with data written under another version of a
+ * package it holds. Newer than ours: hold until we upgrade. Older: restamp through the recipes between.
+ * The same, or a package we don't hold, or no version on the wire: take as is.
+ */
+export declare function versionGate(theirs: string | undefined, installed: {
+    package: string;
+    version: string;
+}[]): {
+    kind: "take";
+} | {
+    kind: "hold";
+    package: string;
+    theirs: string;
+    ours: string;
+} | {
+    kind: "restamp";
+    package: string;
+    theirs: string;
+    ours: string;
+};
 /** Verify a border wrapper from another owner: its log against the owner's key, and its values against the log. */
 export declare function verifyBorder(w: {
     records: Record[];