@earendil-works/chord 1.4.0 → 1.5.1

package/dist/host/uuid.js

@@ -0,0 +1,38 @@
+// UUIDv7 (§3, code copied from pi-ai's `uuidv7`): time-ordered ids, minted for host incarnations.
+const MAX_SEQUENCE = (1n << 41n) - 1n;
+/** The last timestamp used: a clock going backwards keeps the ids ordered. */
+let lastTimestamp = -1;
+/** A random start, then incremented per id, so ids within one millisecond stay ordered and unique. */
+let sequence;
+/** A time-ordered UUIDv7. */
+export function uuidv7() {
+    const timestamp = Math.max(Date.now(), lastTimestamp);
+    lastTimestamp = timestamp;
+    const bytes = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(bytes);
+    if (sequence === undefined) {
+        sequence =
+            (BigInt(bytes[1]) << 32n) |
+                (BigInt(bytes[2]) << 24n) |
+                (BigInt(bytes[3]) << 16n) |
+                (BigInt(bytes[4]) << 8n) |
+                BigInt(bytes[5]);
+    }
+    else {
+        if (sequence === MAX_SEQUENCE)
+            throw new RangeError("UUIDv7 generator sequence exhausted");
+        sequence++;
+    }
+    const time = BigInt(timestamp);
+    for (let index = 5; index >= 0; index--)
+        bytes[index] = Number(time >> BigInt((5 - index) * 8)) & 0xff;
+    bytes[6] = 0x70 | Number((sequence >> 37n) & 0x0fn);
+    bytes[7] = Number((sequence >> 29n) & 0xffn);
+    bytes[8] = 0x80 | Number((sequence >> 23n) & 0x3fn);
+    bytes[9] = Number((sequence >> 15n) & 0xffn);
+    bytes[10] = Number((sequence >> 7n) & 0xffn);
+    bytes[11] = Number((sequence & 0x7fn) << 1n) | (bytes[11] & 0x01);
+    const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0"));
+    return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
+}
+//# sourceMappingURL=uuid.js.map

package/dist/host/uuid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.js","sourceRoot":"","sources":["../../src/host/uuid.ts"],"names":[],"mappings":"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","sourcesContent":["// UUIDv7 (§3, code copied from pi-ai's `uuidv7`): time-ordered ids, minted for host incarnations.\n\nconst MAX_SEQUENCE = (1n << 41n) - 1n;\n\n/** The last timestamp used: a clock going backwards keeps the ids ordered. */\nlet lastTimestamp = -1;\n\n/** A random start, then incremented per id, so ids within one millisecond stay ordered and unique. */\nlet sequence: bigint | undefined;\n\n/** A time-ordered UUIDv7. */\nexport function uuidv7(): string {\n\tconst timestamp = Math.max(Date.now(), lastTimestamp);\n\tlastTimestamp = timestamp;\n\tconst bytes = new Uint8Array(16);\n\tglobalThis.crypto.getRandomValues(bytes);\n\tif (sequence === undefined) {\n\t\tsequence =\n\t\t\t(BigInt(bytes[1]!) << 32n) |\n\t\t\t(BigInt(bytes[2]!) << 24n) |\n\t\t\t(BigInt(bytes[3]!) << 16n) |\n\t\t\t(BigInt(bytes[4]!) << 8n) |\n\t\t\tBigInt(bytes[5]!);\n\t} else {\n\t\tif (sequence === MAX_SEQUENCE) throw new RangeError(\"UUIDv7 generator sequence exhausted\");\n\t\tsequence++;\n\t}\n\tconst time = BigInt(timestamp);\n\tfor (let index = 5; index >= 0; index--) bytes[index] = Number(time >> BigInt((5 - index) * 8)) & 0xff;\n\tbytes[6] = 0x70 | Number((sequence >> 37n) & 0x0fn);\n\tbytes[7] = Number((sequence >> 29n) & 0xffn);\n\tbytes[8] = 0x80 | Number((sequence >> 23n) & 0x3fn);\n\tbytes[9] = Number((sequence >> 15n) & 0xffn);\n\tbytes[10] = Number((sequence >> 7n) & 0xffn);\n\tbytes[11] = Number((sequence & 0x7fn) << 1n) | (bytes[11]! & 0x01);\n\tconst hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, \"0\"));\n\treturn `${hex.slice(0, 4).join(\"\")}-${hex.slice(4, 6).join(\"\")}-${hex.slice(6, 8).join(\"\")}-${hex.slice(8, 10).join(\"\")}-${hex.slice(10).join(\"\")}`;\n}\n"]}

package/dist/index.d.ts

@@ -1,19 +1,30 @@
-export type { Cell } from "./cell.ts";
-export type { AcceptOptions, LinkOptions } from "./connection.ts";
-export type { Context, ContextKey } from "./context/index.ts";
-export { type Accepts, type Adapter, type AnyContract, bind, coverage, type Description, type HostFamily, type HostNamed, hostFamily, hostNamed, type ImplementationOf, type InputOf, type LocalContract, local, method, opaque, type Placement, type PlacementFor, type Ref, type RemoteContract, remote, } from "./contract.ts";
-export type { EventOf, Resource, ResourceDeclaration, Subscribable, ValueOf } from "./declare.ts";
-export type { Draft } from "./delta/index.ts";
-export { ChordError, type ChordErrorCode, forbidden, invalid, isChordError } from "./errors.ts";
-export type { ConnectOptions, PrincipalMatch, PrincipalPattern, Route } from "./host.ts";
-export { createHost, defineFacet, type Facet, type FacetApi, type FacetDefinition, type FacetLoader, type Host, type HostOptions, type LoadOptions, type PluginRef, type RootOptions, } from "./host.ts";
-export { type CopyJsonOptions, copyJson, isJsonValue, type JsonRepresentation, type JsonValue } from "./json.ts";
-export { type IpcChannel, inflateMessage, ipcLink, type Link, memoryLinkPair, PACK_THRESHOLD, type WebSocketLike, type WebSocketLinkOptions, webSocketLink, } from "./link.ts";
-export type { Factory, HostServeOptions, Lifetime, ReferencedServeOptions, Self, ServeOptions, ServeOptionsFor, StateInit, StateOptions, } from "./object.ts";
-export { defineRegistry, type Registry, type RegistryTable, type RegistryView } from "./registry.ts";
-export type { ReloadOptions, ReloadReport } from "./reload.ts";
-export { type AttachedReplicatedState, type MutableReplicatedState, type ReplicatedState, type ReplicatedStateDelivery, type ReplicatedStateSource, type ReplicatedStateSourceAttachment, type ReplicatedStateSourceFrame, type ReplicatedStateSourceOptions, replicatedState, } from "./state.ts";
-export type { Ctx, GetOptions, Readable, RefStatus, Shape, StateEvent } from "./types.ts";
-export { acceptWebSockets, type WebSocketAcceptOptions, type WebSocketServerLike } from "./websocket.ts";
-export { type Frame, PROTOCOL_VERSION } from "./wire.ts";
+export * from "./contracts/index.ts";
+export * from "./data/index.ts";
+export * from "./documents/index.ts";
+export * from "./host/index.ts";
+export * from "./jobs/index.ts";
+export * from "./link/index.ts";
+export * from "./registries/index.ts";
+export * from "./state/index.ts";
+/** @internal The store's surface for adapters (slice 6b §2.1). */
+export { type DecodedRow, OwnerTable, StoreOwnerTables } from "./store/adapter.ts";
+/** @internal The sync layer's batch apply (slice 6b §1.6). */
+export { applyBatch } from "./store/apply-batch.ts";
+/** @internal */
+export type { Claimant } from "./store/claims.ts";
+/** @internal */
+export { type DocumentAddress, type DocumentContent, type DocumentEntry, type DocumentHistory, type DocumentPoint, type DocumentRecord, type DocumentScope, findDocument, findDocumentEntry, insertDocument, listDocumentEntries, listDocuments, loadContent, loadDocument, type OwnedDocumentEntry, readDocument, readDocumentEntry, retireRecord, type StoredDocument, writeContent, } from "./store/engine.ts";
+/** @internal */
+export type { WhereNode } from "./store/expression.ts";
+export * from "./store/index.ts";
+/** @internal */
+export type { EncodedRow } from "./store/rows.ts";
+/** @internal */
+export type { Order } from "./store/sql.ts";
+/** @internal */
+export type { StagedWrite, Step } from "./store/step.ts";
+/** @internal */
+export type { ChordStore, SeriesCommit, SeriesResult } from "./store/store.ts";
+export * from "./surfaces/index.ts";
+export { CHORD_TELEMETRY_SCHEMA, type ChordSpanName } from "./telemetry.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAClE,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EACN,KAAK,OAAO,EACZ,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,IAAI,EACJ,QAAQ,EACR,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,SAAS,EACd,UAAU,EACV,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,KAAK,EACL,MAAM,EACN,MAAM,EACN,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,GAAG,EACR,KAAK,cAAc,EACnB,MAAM,GACN,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAClG,YAAY,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,KAAK,cAAc,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChG,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AACzF,OAAO,EACN,UAAU,EACV,WAAW,EACX,KAAK,KAAK,EACV,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,IAAI,EACT,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,WAAW,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AACjH,OAAO,EACN,KAAK,UAAU,EACf,cAAc,EACd,OAAO,EACP,KAAK,IAAI,EACT,cAAc,EACd,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,aAAa,GACb,MAAM,WAAW,CAAC;AACnB,YAAY,EACX,OAAO,EACP,gBAAgB,EAChB,QAAQ,EACR,sBAAsB,EACtB,IAAI,EACJ,YAAY,EACZ,eAAe,EACf,SAAS,EACT,YAAY,GACZ,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AACrG,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EACN,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,+BAA+B,EACpC,KAAK,0BAA0B,EAC/B,KAAK,4BAA4B,EACjC,eAAe,GACf,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC1F,OAAO,EAAE,gBAAgB,EAAE,KAAK,sBAAsB,EAAE,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACzG,OAAO,EAAE,KAAK,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,kEAAkE;AAClE,OAAO,EAAE,KAAK,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACnF,8DAA8D;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,gBAAgB;AAChB,YAAY,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,gBAAgB;AAChB,OAAO,EACN,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,WAAW,EACX,YAAY,EACZ,KAAK,kBAAkB,EACvB,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,KAAK,cAAc,EACnB,YAAY,GACZ,MAAM,mBAAmB,CAAC;AAC3B,gBAAgB;AAChB,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,cAAc,kBAAkB,CAAC;AACjC,gBAAgB;AAChB,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,gBAAgB;AAChB,YAAY,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,gBAAgB;AAChB,YAAY,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACzD,gBAAgB;AAChB,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAC/E,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,sBAAsB,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -1,10 +1,21 @@
-export { bind, coverage, hostFamily, hostNamed, local, method, opaque, remote, } from "./contract.js";
-export { ChordError, forbidden, invalid, isChordError } from "./errors.js";
-export { createHost, defineFacet, } from "./host.js";
-export { copyJson, isJsonValue } from "./json.js";
-export { inflateMessage, ipcLink, memoryLinkPair, PACK_THRESHOLD, webSocketLink, } from "./link.js";
-export { defineRegistry } from "./registry.js";
-export { replicatedState, } from "./state.js";
-export { acceptWebSockets } from "./websocket.js";
-export { PROTOCOL_VERSION } from "./wire.js";
+// Chord (`@earendil-works/chord`, v2, experimental): every layer's API for apps, and the store's surface for adapters
+// (Durable's `StoreStorage`), marked internal. The Node components and the client surfaces are subpaths (`/http`,
+// `/workers`, `/plugins`, `/app`, `/surfaces`, `/web`, `/react`, `/tui`).
+export * from "./contracts/index.js";
+export * from "./data/index.js";
+export * from "./documents/index.js";
+export * from "./host/index.js";
+export * from "./jobs/index.js";
+export * from "./link/index.js";
+export * from "./registries/index.js";
+export * from "./state/index.js";
+/** @internal The store's surface for adapters (slice 6b §2.1). */
+export { OwnerTable, StoreOwnerTables } from "./store/adapter.js";
+/** @internal The sync layer's batch apply (slice 6b §1.6). */
+export { applyBatch } from "./store/apply-batch.js";
+/** @internal */
+export { findDocument, findDocumentEntry, insertDocument, listDocumentEntries, listDocuments, loadContent, loadDocument, readDocument, readDocumentEntry, retireRecord, writeContent, } from "./store/engine.js";
+export * from "./store/index.js";
+export * from "./surfaces/index.js";
+export { CHORD_TELEMETRY_SCHEMA } from "./telemetry.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAIN,IAAI,EACJ,QAAQ,EAIR,UAAU,EACV,SAAS,EAIT,KAAK,EACL,MAAM,EACN,MAAM,EAKN,MAAM,GACN,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,UAAU,EAAuB,SAAS,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhG,OAAO,EACN,UAAU,EACV,WAAW,GAUX,MAAM,WAAW,CAAC;AACnB,OAAO,EAAwB,QAAQ,EAAE,WAAW,EAA2C,MAAM,WAAW,CAAC;AACjH,OAAO,EAEN,cAAc,EACd,OAAO,EAEP,cAAc,EACd,cAAc,EAGd,aAAa,GACb,MAAM,WAAW,CAAC;AAYnB,OAAO,EAAE,cAAc,EAAwD,MAAM,eAAe,CAAC;AAErG,OAAO,EASN,eAAe,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,gBAAgB,EAAyD,MAAM,gBAAgB,CAAC;AACzG,OAAO,EAAc,gBAAgB,EAAE,MAAM,WAAW,CAAC","sourcesContent":["export type { Cell } from \"./cell.ts\";\nexport type { AcceptOptions, LinkOptions } from \"./connection.ts\";\nexport type { Context, ContextKey } from \"./context/index.ts\";\nexport {\n\ttype Accepts,\n\ttype Adapter,\n\ttype AnyContract,\n\tbind,\n\tcoverage,\n\ttype Description,\n\ttype HostFamily,\n\ttype HostNamed,\n\thostFamily,\n\thostNamed,\n\ttype ImplementationOf,\n\ttype InputOf,\n\ttype LocalContract,\n\tlocal,\n\tmethod,\n\topaque,\n\ttype Placement,\n\ttype PlacementFor,\n\ttype Ref,\n\ttype RemoteContract,\n\tremote,\n} from \"./contract.ts\";\nexport type { EventOf, Resource, ResourceDeclaration, Subscribable, ValueOf } from \"./declare.ts\";\nexport type { Draft } from \"./delta/index.ts\";\nexport { ChordError, type ChordErrorCode, forbidden, invalid, isChordError } from \"./errors.ts\";\nexport type { ConnectOptions, PrincipalMatch, PrincipalPattern, Route } from \"./host.ts\";\nexport {\n\tcreateHost,\n\tdefineFacet,\n\ttype Facet,\n\ttype FacetApi,\n\ttype FacetDefinition,\n\ttype FacetLoader,\n\ttype Host,\n\ttype HostOptions,\n\ttype LoadOptions,\n\ttype PluginRef,\n\ttype RootOptions,\n} from \"./host.ts\";\nexport { type CopyJsonOptions, copyJson, isJsonValue, type JsonRepresentation, type JsonValue } from \"./json.ts\";\nexport {\n\ttype IpcChannel,\n\tinflateMessage,\n\tipcLink,\n\ttype Link,\n\tmemoryLinkPair,\n\tPACK_THRESHOLD,\n\ttype WebSocketLike,\n\ttype WebSocketLinkOptions,\n\twebSocketLink,\n} from \"./link.ts\";\nexport type {\n\tFactory,\n\tHostServeOptions,\n\tLifetime,\n\tReferencedServeOptions,\n\tSelf,\n\tServeOptions,\n\tServeOptionsFor,\n\tStateInit,\n\tStateOptions,\n} from \"./object.ts\";\nexport { defineRegistry, type Registry, type RegistryTable, type RegistryView } from \"./registry.ts\";\nexport type { ReloadOptions, ReloadReport } from \"./reload.ts\";\nexport {\n\ttype AttachedReplicatedState,\n\ttype MutableReplicatedState,\n\ttype ReplicatedState,\n\ttype ReplicatedStateDelivery,\n\ttype ReplicatedStateSource,\n\ttype ReplicatedStateSourceAttachment,\n\ttype ReplicatedStateSourceFrame,\n\ttype ReplicatedStateSourceOptions,\n\treplicatedState,\n} from \"./state.ts\";\nexport type { Ctx, GetOptions, Readable, RefStatus, Shape, StateEvent } from \"./types.ts\";\nexport { acceptWebSockets, type WebSocketAcceptOptions, type WebSocketServerLike } from \"./websocket.ts\";\nexport { type Frame, PROTOCOL_VERSION } from \"./wire.ts\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sHAAsH;AACtH,kHAAkH;AAClH,0EAA0E;AAE1E,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,kEAAkE;AAClE,OAAO,EAAmB,UAAU,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACnF,8DAA8D;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGpD,gBAAgB;AAChB,OAAO,EAQN,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,WAAW,EACX,YAAY,EAEZ,YAAY,EACZ,iBAAiB,EACjB,YAAY,EAEZ,YAAY,GACZ,MAAM,mBAAmB,CAAC;AAG3B,cAAc,kBAAkB,CAAC;AASjC,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,sBAAsB,EAAsB,MAAM,gBAAgB,CAAC","sourcesContent":["// Chord (`@earendil-works/chord`, v2, experimental): every layer's API for apps, and the store's surface for adapters\n// (Durable's `StoreStorage`), marked internal. The Node components and the client surfaces are subpaths (`/http`,\n// `/workers`, `/plugins`, `/app`, `/surfaces`, `/web`, `/react`, `/tui`).\n\nexport * from \"./contracts/index.ts\";\nexport * from \"./data/index.ts\";\nexport * from \"./documents/index.ts\";\nexport * from \"./host/index.ts\";\nexport * from \"./jobs/index.ts\";\nexport * from \"./link/index.ts\";\nexport * from \"./registries/index.ts\";\nexport * from \"./state/index.ts\";\n/** @internal The store's surface for adapters (slice 6b §2.1). */\nexport { type DecodedRow, OwnerTable, StoreOwnerTables } from \"./store/adapter.ts\";\n/** @internal The sync layer's batch apply (slice 6b §1.6). */\nexport { applyBatch } from \"./store/apply-batch.ts\";\n/** @internal */\nexport type { Claimant } from \"./store/claims.ts\";\n/** @internal */\nexport {\n\ttype DocumentAddress,\n\ttype DocumentContent,\n\ttype DocumentEntry,\n\ttype DocumentHistory,\n\ttype DocumentPoint,\n\ttype DocumentRecord,\n\ttype DocumentScope,\n\tfindDocument,\n\tfindDocumentEntry,\n\tinsertDocument,\n\tlistDocumentEntries,\n\tlistDocuments,\n\tloadContent,\n\tloadDocument,\n\ttype OwnedDocumentEntry,\n\treadDocument,\n\treadDocumentEntry,\n\tretireRecord,\n\ttype StoredDocument,\n\twriteContent,\n} from \"./store/engine.ts\";\n/** @internal */\nexport type { WhereNode } from \"./store/expression.ts\";\nexport * from \"./store/index.ts\";\n/** @internal */\nexport type { EncodedRow } from \"./store/rows.ts\";\n/** @internal */\nexport type { Order } from \"./store/sql.ts\";\n/** @internal */\nexport type { StagedWrite, Step } from \"./store/step.ts\";\n/** @internal */\nexport type { ChordStore, SeriesCommit, SeriesResult } from \"./store/store.ts\";\nexport * from \"./surfaces/index.ts\";\nexport { CHORD_TELEMETRY_SCHEMA, type ChordSpanName } from \"./telemetry.ts\";\n"]}

package/dist/jobs/definition.d.ts

@@ -0,0 +1,96 @@
+import type { Schema, Static } from "../contracts/index.ts";
+import { type Snapshot } from "../contracts/snapshot.ts";
+import type { ChordError, PluginError } from "../data/index.ts";
+import type { JsonObject, StateDefinition } from "../documents/index.ts";
+/** What `defineJob` takes besides the name. */
+export type JobOptions<A extends Schema, R extends Schema, D extends StateDefinition<JsonObject, false, boolean> | undefined> = {
+    /** The job's version; every change of its args, result or state bumps it. */
+    readonly version: number;
+    /** The run's arguments: closed objects, JSON only (`running` carries them), checked at every start. */
+    readonly args: A;
+    /** What `run` returns; not validated. */
+    readonly result: R;
+    /**
+     * A singleton document definition: one document per run, `ctx.state` in `run`, `outcome.state` in `finish`; a
+     * persisted job's is persisted (`persist: true`, its `checkpointWhen`).
+     */
+    readonly state?: D;
+    /** At most this many runs running or finishing per object; a start beyond it rejects `unavailable/busy`. */
+    readonly concurrency?: number;
+    /** Per older version, how its args and result map forwards (used from slice 7 on; checked now). */
+    readonly accepts?: JobAccepts<A, R>;
+    /**
+     * Persists the runs in the object's store (slice 6b; only in `local` types with empty params, P3): how a run cut
+     * off by a crash or a stop resumes, `rerun` (its `run` again: idempotent work) or `abandon` (`finish` gets `failed {
+     * aborted, reason: "restart" }`). Its result is JSON only (no `bytes()`).
+     */
+    readonly persist?: JobPersistence;
+};
+/** How a persisted job's runs resume after a crash or a stop. */
+export type JobPersistence = {
+    readonly resume: "rerun" | "abandon";
+};
+/** Per older version, its mappings forwards: its args to the current args, its result to the current result. */
+export type JobAccepts<A extends Schema = Schema, R extends Schema = Schema> = {
+    readonly [version: number]: {
+        readonly args: (old: never) => Static<A>;
+        readonly result: (old: never) => Static<R>;
+    };
+};
+/** The value of a job's state document: the definition's document, `undefined` without one. */
+type StateOf<D> = D extends StateDefinition<infer T, false, boolean> ? T : undefined;
+/** What a run ended with, as `finish` and `outcome` get it: its args and state, and its result or its error. */
+export type Outcome<A, R, S> = {
+    readonly id: string;
+    readonly args: A;
+    readonly state: S;
+} & ({
+    readonly kind: "done";
+    readonly result: R;
+} | {
+    readonly kind: "failed";
+    readonly error: JobError;
+});
+/**
+ * Why a run failed: `run` threw (reported as `job_failed`; anything but a ChordError or PluginError becomes a
+ * PluginError `internal` with its message), it was aborted (`abort`: `abort(id)`; `restart`: cut off by its attempt's
+ * seal while the object continues, or a persisted run abandoned after a crash; `reload` comes with slice 7), or a
+ * persisted run was cut off five times in a row (`restart_limit`, D6).
+ */
+export type JobError = {
+    readonly kind: "threw";
+    readonly error: ChordError | PluginError;
+} | {
+    readonly kind: "aborted";
+    readonly reason: "abort" | "reload" | "restart";
+} | {
+    readonly kind: "restart_limit";
+    readonly restarts: number;
+};
+/** Declares a job: owned work a call starts that outlives it (§15). */
+export declare function defineJob<const A extends Schema, const R extends Schema, D extends StateDefinition<JsonObject, false, boolean> | undefined = undefined>(name: string, options: JobOptions<A, R, D>): JobDefinition<Static<A>, Static<R>, StateOf<D>>;
+/** A declared job; `A`, `R` and `S` are its args, result and state document (`undefined` without one). */
+export declare class JobDefinition<A, R, S> {
+    readonly name: string;
+    readonly version: number;
+    /** The args schema, Chord's copy; its compiled check is cached by this snapshot. */
+    readonly args: Snapshot;
+    readonly result: Snapshot;
+    readonly state: StateDefinition<JsonObject, false, boolean> | undefined;
+    readonly concurrency: number | undefined;
+    /** The older versions' mappings, checked at declaration; slice 7 maps older runs with them. */
+    readonly accepts: JobAccepts;
+    /** How its runs persist; `undefined` for a job in memory. */
+    readonly persist: JobPersistence | undefined;
+    /** `hash64` of its args', result's and state's normal forms: a stored run of another fingerprint is blocked. */
+    readonly fingerprint: string;
+    /** Type only: the args, result and state types. */
+    readonly "~types"?: {
+        readonly args: A;
+        readonly result: R;
+        readonly state: S;
+    };
+    constructor(name: string, version: number, args: Snapshot, result: Snapshot, state: StateDefinition<JsonObject, false, boolean> | undefined, concurrency: number | undefined, accepts: JobAccepts, persist: JobPersistence | undefined, fingerprint: string);
+}
+export {};
+//# sourceMappingURL=definition.d.ts.map

package/dist/jobs/definition.d.ts.map

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

package/dist/jobs/definition.js

@@ -0,0 +1,83 @@
+// Job definitions (§15): `defineJob(name, …)`, the checks of a declaration, and the types of what a run ends with.
+import { checkKeys, entriesOf } from "../contracts/declare.js";
+import { checkName, hash64 } from "../contracts/internal.js";
+import { snapshotArguments, snapshotSchema } from "../contracts/snapshot.js";
+/** Declares a job: owned work a call starts that outlives it (§15). */
+export function defineJob(name, options) {
+    // Declaration policy: JavaScript callers reach every check below.
+    checkName(name, "A job name");
+    checkKeys(options, ["version", "args", "result", "state", "concurrency", "accepts", "persist"], name);
+    const { version, state, concurrency, accepts, persist } = options;
+    if (!Number.isSafeInteger(version) || version < 1)
+        throw new Error(`${name}.version: expected a positive integer`);
+    const args = snapshotArguments(options.args, `${name}.args`);
+    if (args.bytes)
+        throw new Error(`${name}.args: job arguments are JSON (running carries them); no bytes()`);
+    const result = snapshotSchema(options.result, `${name}.result`);
+    if (state?.keyed)
+        throw new Error(`${name}.state: expected a singleton document definition`);
+    if (persist !== undefined)
+        checkPersistence(persist, state, result, name);
+    if (concurrency !== undefined && !(Number.isSafeInteger(concurrency) && concurrency > 0)) {
+        throw new Error(`${name}.concurrency: expected a positive integer`);
+    }
+    if (accepts !== undefined)
+        checkJobAccepts(accepts, version, `${name}.accepts`);
+    const fingerprint = hash64(JSON.stringify({ args: args.normal, result: result.normal, state: state?.fingerprint ?? null }));
+    return new JobDefinition(name, version, args, result, state, concurrency, accepts ?? {}, persist, fingerprint);
+}
+/** A persisted job's declaration: a resume rule, a persisted state document (if any), a JSON-only result. */
+function checkPersistence(persist, state, result, name) {
+    checkKeys(persist, ["resume"], `${name}.persist`);
+    const { resume } = persist;
+    if (resume !== "rerun" && resume !== "abandon")
+        throw new Error(`${name}.persist.resume: expected "rerun" or "abandon"`);
+    if (state !== undefined && !state.persist) {
+        throw new Error(`${name}.state: a persisted job's state is a persisted document (persist: true)`);
+    }
+    if (result.bytes)
+        throw new Error(`${name}.result: a persisted job's result is JSON (it is stored); no bytes()`);
+}
+/** Checks an accepts table's shape: older versions only, each with an `args` and a `result` function. */
+function checkJobAccepts(accepts, version, path) {
+    for (const [key, adapter] of entriesOf(accepts, path)) {
+        const older = Number(key);
+        if (!Number.isSafeInteger(older) || older < 1 || older >= version) {
+            throw new Error(`${path}[${key}]: not an older version`);
+        }
+        checkKeys(adapter, ["args", "result"], `${path}[${key}]`);
+        const { args, result } = adapter;
+        if (typeof args !== "function")
+            throw new Error(`${path}[${key}].args: expected a function`);
+        if (typeof result !== "function")
+            throw new Error(`${path}[${key}].result: expected a function`);
+    }
+}
+/** A declared job; `A`, `R` and `S` are its args, result and state document (`undefined` without one). */
+export class JobDefinition {
+    name;
+    version;
+    /** The args schema, Chord's copy; its compiled check is cached by this snapshot. */
+    args;
+    result;
+    state;
+    concurrency;
+    /** The older versions' mappings, checked at declaration; slice 7 maps older runs with them. */
+    accepts;
+    /** How its runs persist; `undefined` for a job in memory. */
+    persist;
+    /** `hash64` of its args', result's and state's normal forms: a stored run of another fingerprint is blocked. */
+    fingerprint;
+    constructor(name, version, args, result, state, concurrency, accepts, persist, fingerprint) {
+        this.name = name;
+        this.version = version;
+        this.args = args;
+        this.result = result;
+        this.state = state;
+        this.concurrency = concurrency;
+        this.accepts = accepts;
+        this.persist = persist;
+        this.fingerprint = fingerprint;
+    }
+}
+//# sourceMappingURL=definition.js.map

package/dist/jobs/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../src/jobs/definition.ts"],"names":[],"mappings":"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","sourcesContent":["// Job definitions (§15): `defineJob(name, …)`, the checks of a declaration, and the types of what a run ends with.\n\nimport { checkKeys, entriesOf } from \"../contracts/declare.ts\";\nimport type { Schema, Static } from \"../contracts/index.ts\";\nimport { checkName, hash64 } from \"../contracts/internal.ts\";\nimport { type Snapshot, snapshotArguments, snapshotSchema } from \"../contracts/snapshot.ts\";\nimport type { ChordError, PluginError } from \"../data/index.ts\";\nimport type { JsonObject, StateDefinition } from \"../documents/index.ts\";\n\n/** What `defineJob` takes besides the name. */\nexport type JobOptions<\n\tA extends Schema,\n\tR extends Schema,\n\tD extends StateDefinition<JsonObject, false, boolean> | undefined,\n> = {\n\t/** The job's version; every change of its args, result or state bumps it. */\n\treadonly version: number;\n\t/** The run's arguments: closed objects, JSON only (`running` carries them), checked at every start. */\n\treadonly args: A;\n\t/** What `run` returns; not validated. */\n\treadonly result: R;\n\t/**\n\t * A singleton document definition: one document per run, `ctx.state` in `run`, `outcome.state` in `finish`; a\n\t * persisted job's is persisted (`persist: true`, its `checkpointWhen`).\n\t */\n\treadonly state?: D;\n\t/** At most this many runs running or finishing per object; a start beyond it rejects `unavailable/busy`. */\n\treadonly concurrency?: number;\n\t/** Per older version, how its args and result map forwards (used from slice 7 on; checked now). */\n\treadonly accepts?: JobAccepts<A, R>;\n\t/**\n\t * Persists the runs in the object's store (slice 6b; only in `local` types with empty params, P3): how a run cut\n\t * off by a crash or a stop resumes, `rerun` (its `run` again: idempotent work) or `abandon` (`finish` gets `failed {\n\t * aborted, reason: \"restart\" }`). Its result is JSON only (no `bytes()`).\n\t */\n\treadonly persist?: JobPersistence;\n};\n\n/** How a persisted job's runs resume after a crash or a stop. */\nexport type JobPersistence = { readonly resume: \"rerun\" | \"abandon\" };\n\n/** Per older version, its mappings forwards: its args to the current args, its result to the current result. */\nexport type JobAccepts<A extends Schema = Schema, R extends Schema = Schema> = {\n\treadonly [version: number]: { readonly args: (old: never) => Static<A>; readonly result: (old: never) => Static<R> };\n};\n\n/** The value of a job's state document: the definition's document, `undefined` without one. */\ntype StateOf<D> = D extends StateDefinition<infer T, false, boolean> ? T : undefined;\n\n/** What a run ended with, as `finish` and `outcome` get it: its args and state, and its result or its error. */\nexport type Outcome<A, R, S> = { readonly id: string; readonly args: A; readonly state: S } & (\n\t| { readonly kind: \"done\"; readonly result: R }\n\t| { readonly kind: \"failed\"; readonly error: JobError }\n);\n\n/**\n * Why a run failed: `run` threw (reported as `job_failed`; anything but a ChordError or PluginError becomes a\n * PluginError `internal` with its message), it was aborted (`abort`: `abort(id)`; `restart`: cut off by its attempt's\n * seal while the object continues, or a persisted run abandoned after a crash; `reload` comes with slice 7), or a\n * persisted run was cut off five times in a row (`restart_limit`, D6).\n */\nexport type JobError =\n\t| { readonly kind: \"threw\"; readonly error: ChordError | PluginError }\n\t| { readonly kind: \"aborted\"; readonly reason: \"abort\" | \"reload\" | \"restart\" }\n\t| { readonly kind: \"restart_limit\"; readonly restarts: number };\n\n/** Declares a job: owned work a call starts that outlives it (§15). */\nexport function defineJob<\n\tconst A extends Schema,\n\tconst R extends Schema,\n\tD extends StateDefinition<JsonObject, false, boolean> | undefined = undefined,\n>(name: string, options: JobOptions<A, R, D>): JobDefinition<Static<A>, Static<R>, StateOf<D>> {\n\t// Declaration policy: JavaScript callers reach every check below.\n\tcheckName(name, \"A job name\");\n\tcheckKeys(options, [\"version\", \"args\", \"result\", \"state\", \"concurrency\", \"accepts\", \"persist\"], name);\n\tconst { version, state, concurrency, accepts, persist } = options;\n\tif (!Number.isSafeInteger(version) || version < 1) throw new Error(`${name}.version: expected a positive integer`);\n\tconst args = snapshotArguments(options.args, `${name}.args`);\n\tif (args.bytes) throw new Error(`${name}.args: job arguments are JSON (running carries them); no bytes()`);\n\tconst result = snapshotSchema(options.result, `${name}.result`);\n\tif (state?.keyed) throw new Error(`${name}.state: expected a singleton document definition`);\n\tif (persist !== undefined) checkPersistence(persist, state, result, name);\n\tif (concurrency !== undefined && !(Number.isSafeInteger(concurrency) && concurrency > 0)) {\n\t\tthrow new Error(`${name}.concurrency: expected a positive integer`);\n\t}\n\tif (accepts !== undefined) checkJobAccepts(accepts, version, `${name}.accepts`);\n\tconst fingerprint = hash64(\n\t\tJSON.stringify({ args: args.normal, result: result.normal, state: state?.fingerprint ?? null }),\n\t);\n\treturn new JobDefinition(name, version, args, result, state, concurrency, accepts ?? {}, persist, fingerprint);\n}\n\n/** A persisted job's declaration: a resume rule, a persisted state document (if any), a JSON-only result. */\nfunction checkPersistence(\n\tpersist: unknown,\n\tstate: StateDefinition<JsonObject, false, boolean> | undefined,\n\tresult: Snapshot,\n\tname: string,\n): void {\n\tcheckKeys(persist, [\"resume\"], `${name}.persist`);\n\tconst { resume } = persist as { readonly resume?: unknown };\n\tif (resume !== \"rerun\" && resume !== \"abandon\")\n\t\tthrow new Error(`${name}.persist.resume: expected \"rerun\" or \"abandon\"`);\n\tif (state !== undefined && !state.persist) {\n\t\tthrow new Error(`${name}.state: a persisted job's state is a persisted document (persist: true)`);\n\t}\n\tif (result.bytes) throw new Error(`${name}.result: a persisted job's result is JSON (it is stored); no bytes()`);\n}\n\n/** Checks an accepts table's shape: older versions only, each with an `args` and a `result` function. */\nfunction checkJobAccepts(accepts: unknown, version: number, path: string): void {\n\tfor (const [key, adapter] of entriesOf(accepts, path)) {\n\t\tconst older = Number(key);\n\t\tif (!Number.isSafeInteger(older) || older < 1 || older >= version) {\n\t\t\tthrow new Error(`${path}[${key}]: not an older version`);\n\t\t}\n\t\tcheckKeys(adapter, [\"args\", \"result\"], `${path}[${key}]`);\n\t\tconst { args, result } = adapter as { readonly args?: unknown; readonly result?: unknown };\n\t\tif (typeof args !== \"function\") throw new Error(`${path}[${key}].args: expected a function`);\n\t\tif (typeof result !== \"function\") throw new Error(`${path}[${key}].result: expected a function`);\n\t}\n}\n\n/** A declared job; `A`, `R` and `S` are its args, result and state document (`undefined` without one). */\nexport class JobDefinition<A, R, S> {\n\treadonly name: string;\n\treadonly version: number;\n\t/** The args schema, Chord's copy; its compiled check is cached by this snapshot. */\n\treadonly args: Snapshot;\n\treadonly result: Snapshot;\n\treadonly state: StateDefinition<JsonObject, false, boolean> | undefined;\n\treadonly concurrency: number | undefined;\n\t/** The older versions' mappings, checked at declaration; slice 7 maps older runs with them. */\n\treadonly accepts: JobAccepts;\n\t/** How its runs persist; `undefined` for a job in memory. */\n\treadonly persist: JobPersistence | undefined;\n\t/** `hash64` of its args', result's and state's normal forms: a stored run of another fingerprint is blocked. */\n\treadonly fingerprint: string;\n\t/** Type only: the args, result and state types. */\n\tdeclare readonly \"~types\"?: { readonly args: A; readonly result: R; readonly state: S };\n\n\tconstructor(\n\t\tname: string,\n\t\tversion: number,\n\t\targs: Snapshot,\n\t\tresult: Snapshot,\n\t\tstate: StateDefinition<JsonObject, false, boolean> | undefined,\n\t\tconcurrency: number | undefined,\n\t\taccepts: JobAccepts,\n\t\tpersist: JobPersistence | undefined,\n\t\tfingerprint: string,\n\t) {\n\t\tthis.name = name;\n\t\tthis.version = version;\n\t\tthis.args = args;\n\t\tthis.result = result;\n\t\tthis.state = state;\n\t\tthis.concurrency = concurrency;\n\t\tthis.accepts = accepts;\n\t\tthis.persist = persist;\n\t\tthis.fingerprint = fingerprint;\n\t}\n}\n"]}

package/dist/jobs/index.d.ts

@@ -0,0 +1,5 @@
+export { defineJob, type JobAccepts, type JobDefinition, type JobError, type JobOptions, type Outcome, } from "./definition.ts";
+export type { JobCtx, JobHandle, JobImplementation, RunState, StartOptions } from "./job.ts";
+export type { BlockedReason, Run } from "./run.ts";
+export type { RunningEntry } from "./running.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/jobs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/jobs/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACN,SAAS,EACT,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,OAAO,GACZ,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,iBAAiB,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7F,YAAY,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/dist/jobs/index.js

@@ -0,0 +1,3 @@
+// Jobs for apps: declaring a job, its handle, its runs, their outcomes and `running`.
+export { defineJob, } from "./definition.js";
+//# sourceMappingURL=index.js.map

package/dist/jobs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/jobs/index.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EACN,SAAS,GAMT,MAAM,iBAAiB,CAAC","sourcesContent":["// Jobs for apps: declaring a job, its handle, its runs, their outcomes and `running`.\n\nexport {\n\tdefineJob,\n\ttype JobAccepts,\n\ttype JobDefinition,\n\ttype JobError,\n\ttype JobOptions,\n\ttype Outcome,\n} from \"./definition.ts\";\nexport type { JobCtx, JobHandle, JobImplementation, RunState, StartOptions } from \"./job.ts\";\nexport type { BlockedReason, Run } from \"./run.ts\";\nexport type { RunningEntry } from \"./running.ts\";\n"]}

package/dist/jobs/internal.d.ts

@@ -0,0 +1,3 @@
+export { type AnyJobImplementation, type CutReason, Job, type JobOwner } from "./job.ts";
+export { JobRecords, type RecordsOwner } from "./records.ts";
+//# sourceMappingURL=internal.d.ts.map

package/dist/jobs/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/jobs/internal.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,oBAAoB,EAAE,KAAK,SAAS,EAAE,GAAG,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzF,OAAO,EAAE,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/dist/jobs/internal.js

@@ -0,0 +1,4 @@
+// Jobs for Chord's layers: a job's records on its object and the handle an attempt keeps, and what they need.
+export { Job } from "./job.js";
+export { JobRecords } from "./records.js";
+//# sourceMappingURL=internal.js.map

package/dist/jobs/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../../src/jobs/internal.ts"],"names":[],"mappings":"AAAA,8GAA8G;AAE9G,OAAO,EAA6C,GAAG,EAAiB,MAAM,UAAU,CAAC;AACzF,OAAO,EAAE,UAAU,EAAqB,MAAM,cAAc,CAAC","sourcesContent":["// Jobs for Chord's layers: a job's records on its object and the handle an attempt keeps, and what they need.\n\nexport { type AnyJobImplementation, type CutReason, Job, type JobOwner } from \"./job.ts\";\nexport { JobRecords, type RecordsOwner } from \"./records.ts\";\n"]}

package/dist/jobs/job.d.ts

@@ -0,0 +1,149 @@
+import type { TelemetrySpan } from "@earendil-works/pi-telemetry";
+import { type Context } from "../context/index.ts";
+import { ChordError, type Principal } from "../data/index.ts";
+import type { Draft } from "../delta/index.ts";
+import type { CommitPersistence, JsonObject, Tx } from "../documents/index.ts";
+import type { Documents, SealToken, Transaction } from "../documents/internal.ts";
+import { type Ctx } from "../host/index.ts";
+import { type AnyHost, CallContext, type Caller } from "../host/internal.ts";
+import type { JsonValue } from "../json.ts";
+import type { Watchable } from "../watch.ts";
+import type { Outcome } from "./definition.ts";
+import type { JobRecords } from "./records.ts";
+import type { AnyOutcome, JobRun, Run } from "./run.ts";
+import type { RunningEntry } from "./running.ts";
+/** A job's handle, `self.job(Job, { run, finish? })`; `A`, `R` and `S` are its args, result and state. */
+export interface JobHandle<A, R, S> {
+    /**
+     * Starts a run in one transaction on the object's line and resolves with its `Run` after the commit: the args
+     * checked (`invalid/args`); a `key` of an unsettled run returns that run; at the `concurrency` limit (running plus
+     * finishing runs) it rejects `unavailable/busy`. `run` starts after the commit.
+     */
+    start(args: A, context: Context, options?: StartOptions): Promise<Run<Outcome<A, R, S>>>;
+    /** Waits for the outcome of the unsettled run `id`; a settled or unknown id rejects `gone`. */
+    outcome(id: string, context: Context): Promise<Outcome<A, R, S>>;
+    /**
+     * Aborts run `id` (D7, as Durable's `abortTask`): marks it (stored for a persisted job) and fires its `run`'s
+     * signal, resolving `"marked"` once its `run` settled (a run not invoked yet ends `aborted` without one); a
+     * finishing run is only marked, a blocked one dropped (no `finish`; its waiters reject `aborted`). `"terminal"` when
+     * no unsettled run has that id. `context` ends only this wait.
+     */
+    abort(id: string, context: Context): Promise<"marked" | "terminal">;
+    /** The unsettled runs, one entry each in start order, tagged by phase (a JSON watchable, a state member). */
+    readonly running: Watchable<readonly RunningEntry<A, S>[]>;
+}
+/** What `start` and `tx.start` take besides the args. */
+export type StartOptions = {
+    /** Names one run: a start with the key of an unsettled run returns that run (args not compared). */
+    readonly key?: string;
+};
+/** What `self.job` takes: the run and the optional finish. */
+export type JobImplementation<A, R, S, P extends Principal = Principal> = {
+    /** The work, outside transactions; its ctx's abort signal fires on `abort(id)` and on its object's end. */
+    readonly run: (args: A, ctx: JobCtx<P, S>) => Promise<R>;
+    /** Records the outcome in one transaction (only `await tx.*`); the run's record and state document go with it. */
+    readonly finish?: (outcome: Outcome<A, R, S>, tx: Tx) => void | Promise<void>;
+};
+/** A run's ctx: a handler's ctx (the object's principal or the host's), its run's id and, with a state, the state. */
+export type JobCtx<P extends Principal, S> = Ctx<P> & {
+    readonly jobId: string;
+} & ([S] extends [undefined] ? unknown : {
+    readonly state: RunState<S>;
+});
+/** A run's state document. */
+export interface RunState<S> {
+    /** The document's value. */
+    readonly value: S;
+    /**
+     * One transaction on the object's line drafting only this document, under `context` without its abort signal:
+     * admitted while `run` runs (also after an abort, with the run's own ctx), refused `released` once it settled. A
+     * persisted job's change may be `deferred` (D8): adopted and published at once, stored within `withinMs` (1,000 ms by
+     * default) or earlier; a crash loses it. In memory the option changes nothing.
+     */
+    change<T>(fn: (draft: Draft<S>) => T, context: Context, options?: {
+        readonly persistence?: CommitPersistence;
+    }): Promise<T>;
+}
+/** Where a job's handle runs its work: its attempt, as the job sees it. */
+export type JobOwner = {
+    readonly host: AnyHost;
+    /** Whom runs act for: the object's principal (remote) or the host's (local), from this host. */
+    readonly caller: Caller;
+    /** The object's context, without an abort signal: runs, state changes and finishes run under it. */
+    readonly context: Context;
+    /** Aborted when the attempt is sealed: a finish's backoff waits under it. */
+    readonly signal: AbortSignal;
+    /** The attempt's seal token: its starts and finishes are transactions under it. */
+    readonly token: SealToken;
+    readonly documents: Documents;
+    /**
+     * Adds running work (a finish, a reservation) to the attempt's calls drain; `cleanup` (its bookkeeping) runs once,
+     * when it settles or when the attempt ends with it still running.
+     */
+    admit(running: Promise<unknown>, cleanup?: () => void): void;
+    /** Adds a run's invocation to the attempt's drain at its end, as `admit`. */
+    admitRun(running: Promise<unknown>, cleanup: () => void): void;
+};
+/**
+ * Why a seal cuts a running in-memory run off: `restart` (its attempt ended while the object continues) or `reload`
+ * (a native restart, slice 7b §8); its outcome is `failed { aborted }` with that reason.
+ */
+export type CutReason = "restart" | "reload";
+/** A job's implementation as Chord calls it, whatever the job's types. */
+export type AnyJobImplementation = {
+    readonly run: (args: JsonValue, ctx: JobContext) => Promise<unknown>;
+    readonly finish?: (outcome: AnyOutcome, tx: Tx) => void | Promise<void>;
+};
+/**
+ * A job as one attempt declares it: its implementation and the invocations and finishes running on the attempt. Starts
+ * are taken while the attempt is live; the object's records keep the runs.
+ */
+export declare class Job implements JobHandle<JsonValue, unknown, JsonValue | undefined> {
+    #private;
+    constructor(records: JobRecords, implementation: AnyJobImplementation, owner: JobOwner);
+    get running(): Watchable<readonly RunningEntry<JsonValue, JsonValue | undefined>[]>;
+    start(args: JsonValue, context: Context, options?: StartOptions): Promise<Run<AnyOutcome>>;
+    outcome(id: string, context: Context): Promise<AnyOutcome>;
+    abort(id: string, context: Context): Promise<"marked" | "terminal">;
+    /** A persisted job's runs, loaded once per object at its first activation (before it goes live). */
+    load(context: Context): Promise<void>;
+    /** The close writer of this job's runs, after the attempt's drain (slice 6b §4.2). */
+    writeAtClose(context: Context): Promise<void>;
+    /** The attempt went live: starts are taken, and the records' waiting runs are invoked or finished here. */
+    live(): void;
+    /**
+     * Stages a run in `tx` (`start`, `tx.start`), in order: the args checked, dedupe by key (runs started earlier in
+     * `tx` included), the concurrency check, then the record and the state document, created in the commit. The run
+     * whose finish `tx` is counts for neither: `finish` may start the same job again, with the same key too. Returns
+     * the run's handle at once; a start that only dedupes stages nothing.
+     */
+    stage(tx: Transaction, args: unknown, context: Context, options: StartOptions): Run<AnyOutcome>;
+    /**
+     * The attempt is sealed with `error`: starts are refused, running invocations are cut off (their signals fire, in
+     * memory they end `aborted` with `reason` and finish on the next live attempt, persisted ones are stopped and
+     * resumed, R3), and the runs finishing here wait for it.
+     */
+    seal(error: ChordError, reason: CutReason): void;
+    /**
+     * Runs `run` for a committed run (with its signal aborted already after an early abort); a persisted run's
+     * reservation commits first (`running`: a crash from then on counts, D6). The reservation, the invocation and the
+     * run's finish are one piece of work in the drain, admitted before plugin code runs: `run` may end its own object
+     * before its first await.
+     */
+    invoke(run: JobRun): void;
+    /**
+     * Runs the finish of `run`, whose outcome is recorded: `finish` with the cleanup in one transaction under the
+     * attempt's token, retried with backoff after a throw (reported), blocked after five in a row. The attempt's seal
+     * stops it without a report or a count; the next live attempt finishes the run.
+     */
+    finish(run: JobRun): void;
+}
+/** A run's ctx: the handler's ctx of its object, its id and, with a state, its state document. */
+export declare class JobContext extends CallContext {
+    readonly jobId: string;
+    readonly state: RunState<JsonObject> | undefined;
+    constructor(context: Context, caller: Caller, host: AnyHost, jobId: string, state: RunState<JsonObject> | undefined);
+    /** Its child under `span` (`ctx.trace`): a job's ctx still, its id and state kept. */
+    traced(span: TelemetrySpan): Ctx;
+}
+//# sourceMappingURL=job.d.ts.map

package/dist/jobs/job.d.ts.map

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