@sanoma-ai/workflows 0.0.0-stage → 0.2.0

package/dist/host.js

@@ -0,0 +1,45 @@
+const LIFETIMES = ["long-lived", "wake-on-schedule"];
+/** True when `schema` has a field at the dotted `path`, looking through optional, nullable and default wrappers. */
+function hasPath(schema, path) {
+    let at = schema;
+    for (const key of path.split(".")) {
+        at = unwrap(at);
+        const shape = at.shape;
+        at = shape?.[key];
+        if (!at)
+            return false;
+    }
+    return true;
+}
+function unwrap(schema) {
+    let at = schema;
+    while ("unwrap" in at && typeof at.unwrap === "function")
+        at = at.unwrap();
+    return at;
+}
+/**
+ * Throws what is wrong with a resource type's `host`: an input or `revision` that names no field,
+ * `secrets` that is not write-only, a `revision` that is, an unknown lifetime, a type apply cannot
+ * change (not `writable`).
+ */
+export function checkHost(what, host, type) {
+    const problems = [];
+    if (!type.writable)
+        problems.push("it must be writable, so apply can create and update it");
+    if (!LIFETIMES.includes(host.capabilities?.lifetime)) {
+        problems.push(`capabilities.lifetime is one of ${LIFETIMES.join(", ")}`);
+    }
+    for (const [input, path] of [...Object.entries(host.inputs ?? {}), ["revision", host.revision]]) {
+        if (typeof path !== "string" || !hasPath(type.schema, path))
+            problems.push(`${input} names no field (${path})`);
+    }
+    if (!type.fields.writeOnly.includes(host.inputs?.secrets))
+        problems.push("inputs.secrets must be a write-only field");
+    if (type.fields.writeOnly.includes(host.revision))
+        problems.push("revision must not be write-only: drift reads it");
+    if (typeof host.outputs !== "function")
+        problems.push("outputs must be a function of the state");
+    if (problems.length)
+        throw new Error(`${what}: its host: ${problems.join("; ")}`);
+}
+//# sourceMappingURL=host.js.map

package/dist/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAqDA,MAAM,SAAS,GAA4B,CAAC,YAAY,EAAE,kBAAkB,CAAC,CAAC;AAE9E,oHAAoH;AACpH,SAAS,OAAO,CAAC,MAAiB,EAAE,IAAY;IAC9C,IAAI,EAAE,GAA0B,MAAM,CAAC;IACvC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAClC,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC;QAChB,MAAM,KAAK,GAAI,EAA2B,CAAC,KAAK,CAAC;QACjD,EAAE,GAAG,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;QAClB,IAAI,CAAC,EAAE;YAAE,OAAO,KAAK,CAAC;IACxB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,MAAM,CAAC,MAAiB;IAC/B,IAAI,EAAE,GAAG,MAAM,CAAC;IAChB,OAAO,QAAQ,IAAI,EAAE,IAAI,OAAO,EAAE,CAAC,MAAM,KAAK,UAAU;QAAE,EAAE,GAAG,EAAE,CAAC,MAAM,EAAe,CAAC;IACxF,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CACvB,IAAY,EACZ,IAAc,EACd,IAA2F;IAE3F,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,CAAC,IAAI,CAAC,QAAQ;QAAE,QAAQ,CAAC,IAAI,CAAC,wDAAwD,CAAC,CAAC;IAC5F,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,EAAE,CAAC;QACrD,QAAQ,CAAC,IAAI,CAAC,mCAAmC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAU,CAAC,EAAE,CAAC;QACzG,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,oBAAoB,IAAI,GAAG,CAAC,CAAC;IAClH,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC;QAAE,QAAQ,CAAC,IAAI,CAAC,2CAA2C,CAAC,CAAC;IACtH,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC;QAAE,QAAQ,CAAC,IAAI,CAAC,iDAAiD,CAAC,CAAC;IACpH,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,UAAU;QAAE,QAAQ,CAAC,IAAI,CAAC,yCAAyC,CAAC,CAAC;IACjG,IAAI,QAAQ,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,eAAe,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACpF,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export { type CallContext, type Connector, type ConnectorSetup, type ConnectorVendor, type Driver, type DriverEnv, type DriverFn, defineConnector, DriverError, type Effect, isOp, type Op, type OpSpec, type ResourceGroup, retryableStatus, type VendorInfo, withSetup, } from "./op.ts";
+export { defineWorkflow, Principal, type ApprovalRequest, type ApprovalResult, type ApprovalState, type Approver, type Builtin, type Ctx, type SleepRequest, type StepOptions, type Use, type WorkflowDefinition, } from "./define.ts";
+export { compareDeclared, type Declared, type Declaring, defineResource, diffDeclared, type FieldReference, type PlanAction, type References, type Resource, type ResourceFields, type ResourceOps, type ResourceSpec, withoutWriteOnly, } from "./resource.ts";
+export { defineConfig, resolveConfig, resolveDatabaseUrl, type ResolvedConfig, type SanomaConfig } from "./config.ts";
+export { type CredentialStatus, credentialsOf } from "./env.ts";
+export { APPLY_WORKFLOW, ApplyInput, type ApplyPlan, type ApplyReport, type ApplyResult, type PlanAnswer, type PlanStep, } from "./apply.ts";
+export { DRIFT_WORKFLOW, type DriftDeclared, type DriftField, type DriftReport, type DriftResult, type DriftStatus, } from "./drift.ts";
+export type { DeclaredResource, ResourceProblem } from "./resources.ts";
+export { allow, allowAll, approve, approvedFor, type Decision, definePolicy, deny, type Policy, type PolicyCall, type PolicyOp, policyOpOf, type RecordedDecision, } from "./policy.ts";
+export { errorCode, type ErrorCode, type ErrorInfo, type InputIssue, invalidInput, PolicyDeniedError, RejectedError, SanomaError, } from "./errors.ts";
+export { jsonlLedger, memoryLedger, postgresLedger, type LedgerBody, type LedgerGroup, type LedgerRecord, type LedgerStore, } from "./ledger.ts";
+export { ApprovalMessage, APPROVALS_EVENT, decisionEventOf } from "./approvals.ts";
+export { RUNTIME_VERSION } from "./version.ts";
+export type { RunArgs } from "./run.ts";
+export { startWorker, type Worker, type WorkerOptions } from "./worker.ts";
+export { generateSecret, isSecret, memorySecrets, type Resolved, resolveSecrets, type Secret, type Secrets, } from "./secret.ts";
+export { resolveRevision, SOURCE_RESOLVE, type Source } from "./source.ts";
+export type { HostCapabilities, HostLifetime, HostOutputs, HostSpec } from "./host.ts";
+export { SanomaClient, type RunsFilter, type RunSummary, type StartOptions, type StoredSecret } from "./client.ts";
+export { dbosClient } from "./db.ts";
+export { approverLabel, credentialReady, DEFAULT_SLEEP_NAME, ENDED_STATUSES, errorMessage, isEnded, isLoopback, mayDecide, problemAt, problemLine, RUN_STATUSES, type RunStatus, } from "./shared.ts";
+export { defineDriver, type DriverImpl, type OpIdOf } from "./op.ts";
+export { defineSteps, type Expect, type RunView, type Seed, type Steps } from "./steps.ts";

package/dist/index.js

@@ -0,0 +1,29 @@
+export { defineConnector, DriverError, isOp, retryableStatus, withSetup, } from "./op.js";
+export { defineWorkflow, Principal, } from "./define.js";
+export { compareDeclared, defineResource, diffDeclared, withoutWriteOnly, } from "./resource.js";
+export { defineConfig, resolveConfig, resolveDatabaseUrl } from "./config.js";
+export { credentialsOf } from "./env.js";
+export { APPLY_WORKFLOW, ApplyInput, } from "./apply.js";
+export { DRIFT_WORKFLOW, } from "./drift.js";
+export { allow, allowAll, approve, approvedFor, definePolicy, deny, policyOpOf, } from "./policy.js";
+export { errorCode, invalidInput, PolicyDeniedError, RejectedError, SanomaError, } from "./errors.js";
+export { jsonlLedger, memoryLedger, postgresLedger, } from "./ledger.js";
+export { ApprovalMessage, APPROVALS_EVENT, decisionEventOf } from "./approvals.js";
+export { RUNTIME_VERSION } from "./version.js";
+export { startWorker } from "./worker.js";
+// `secret` itself is at `@sanoma-ai/workflows/resources`, for data files; this is the drivers' side.
+export { generateSecret, isSecret, memorySecrets, resolveSecrets, } from "./secret.js";
+export { resolveRevision, SOURCE_RESOLVE } from "./source.js";
+export { SanomaClient } from "./client.js";
+// A raw DBOS client on the runtime's database, for tests and tools that read DBOS directly.
+export { dbosClient } from "./db.js";
+// Also at `@sanoma-ai/workflows/shared`, which a browser bundle can import.
+export { approverLabel, credentialReady, DEFAULT_SLEEP_NAME, ENDED_STATUSES, errorMessage, isEnded, isLoopback, mayDecide, problemAt, problemLine, RUN_STATUSES, } from "./shared.js";
+// describeConfig, with the outline and every problem lintWorkflow finds, lives at
+// `@sanoma-ai/workflows/describe`: what a UI renders from, apart from what runs. The worker reads
+// each workflow's outline too, to hold its runs to it.
+export { defineDriver } from "./op.js";
+// Steps for Gherkin tests, as data; Cucumber runs them from `@sanoma-ai/workflows/scenario`.
+export { defineSteps } from "./steps.js";
+// defineFake lives at `@sanoma-ai/workflows/fake`: test tooling, not runtime.
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,eAAe,EACf,WAAW,EAEX,IAAI,EAIJ,eAAe,EAEf,SAAS,GACV,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,cAAc,EACd,SAAS,GAWV,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EAGf,cAAc,EACd,YAAY,EAQZ,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAA0C,MAAM,aAAa,CAAC;AACtH,OAAO,EAAyB,aAAa,EAAE,MAAM,UAAU,CAAC;AAChE,OAAO,EACL,cAAc,EACd,UAAU,GAMX,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,cAAc,GAMf,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,KAAK,EACL,QAAQ,EACR,OAAO,EACP,WAAW,EAEX,YAAY,EACZ,IAAI,EAIJ,UAAU,GAEX,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,SAAS,EAIT,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,WAAW,EACX,YAAY,EACZ,cAAc,GAKf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACnF,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,WAAW,EAAmC,MAAM,aAAa,CAAC;AAC3E,qGAAqG;AACrG,OAAO,EACL,cAAc,EACd,QAAQ,EACR,aAAa,EAEb,cAAc,GAGf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,eAAe,EAAE,cAAc,EAAe,MAAM,aAAa,CAAC;AAE3E,OAAO,EAAE,YAAY,EAA0E,MAAM,aAAa,CAAC;AACnH,4FAA4F;AAC5F,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,4EAA4E;AAC5E,OAAO,EACL,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,OAAO,EACP,UAAU,EACV,SAAS,EACT,SAAS,EACT,WAAW,EACX,YAAY,GAEb,MAAM,aAAa,CAAC;AACrB,kFAAkF;AAClF,kGAAkG;AAClG,uDAAuD;AACvD,OAAO,EAAE,YAAY,EAAgC,MAAM,SAAS,CAAC;AACrE,6FAA6F;AAC7F,OAAO,EAAE,WAAW,EAAoD,MAAM,YAAY,CAAC;AAC3F,8EAA8E"}

package/dist/ledger.d.ts

@@ -0,0 +1,217 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Approver, Principal } from "./define.ts";
+import { type ErrorInfo } from "./errors.ts";
+import type { Effect } from "./op.ts";
+import type { RecordedDecision } from "./policy.ts";
+import type { Run } from "./run.ts";
+/**
+ * The audit record of a run: who started it, every operation call with the policy's
+ * decision, every approval, and how it ended. Records are append-only.
+ *
+ * `id` is deterministic (`<runId>:<type>:<seq>`, `<runId>:<type>:<approvalId>` for an
+ * approval requested or decided, `<runId>:approval.refused:<approvalId>:refused:<n>` for
+ * the nth message an approval ignored) so that when DBOS replays a run after a restart,
+ * the records it writes again have the same ids and the store skips them. `seq` orders a
+ * run's records. `v` is the record format's version; `app` is the config's `appName`.
+ */
+export type LedgerRecord = {
+    v: 1;
+    app: string;
+    id: string;
+    runId: string;
+    seq: number;
+    at: number;
+    actor: Principal;
+    workflow: string;
+    /** Set on every record written while a `ctx.all` member runs; absent outside one. */
+    group?: LedgerGroup;
+} & ({
+    type: "run.started";
+    input: unknown;
+} | {
+    type: "op.called";
+    op: string;
+    /**
+     * The outline node of the call that made it (`OutlineNode.path`): where the step is in the
+     * code. Absent in records written before the worker placed calls (ledgers from 0.1).
+     */
+    node?: string;
+    /**
+     * The step's name: the one the call gave (`{ name }`), or the operation's id. Absent in
+     * records written before steps had names.
+     */
+    name?: string;
+    effect: Effect;
+    input: unknown;
+    /** The policy's decision, with its `reasons` and the policy's `policyVersion` when there are any. */
+    decision: RecordedDecision;
+    output?: unknown;
+    /**
+     * Why the call failed: `{ code?, name, message }`, and the vendor's `status`, `vendorCode`
+     * and `retryable` from a `DriverError`, or the `data` of one of the runtime's errors.
+     */
+    error?: ErrorInfo;
+    durationMs: number;
+    /** Which try produced the output or the final error, from 1. Idempotent operations are retried. */
+    attempt?: number;
+    /** The approval that held the call, when its rejection stopped it. */
+    approval?: string;
+} | {
+    type: "approval.requested";
+    approval: string;
+    /** The outline node of the `ctx.approval` call, or of the held operation's call for a policy request; as for `op.called`. */
+    node?: string;
+    /** The step's name: the title for a `ctx.approval`, the held call's name for a policy request; as for `op.called`. */
+    name?: string;
+    title: string;
+    approver: Approver;
+    requestedBy: "workflow" | "policy";
+    /** The operations the approval stands for, by id. */
+    covers: string[];
+    /** The operation call held, for a policy request. */
+    op?: string;
+    /** The held call's `seq`, which its `op.called` record has, for a policy request. */
+    opSeq?: number;
+}
+/** A message the approval ignored: from someone other than the approver, or not a decision. */
+ | {
+    type: "approval.refused";
+    approval: string;
+    by?: string;
+    reason: string;
+} | {
+    type: "approval.decided";
+    approval: string;
+    decision: "approve" | "reject";
+    by: string;
+    note?: string;
+}
+/**
+ * A `ctx.sleep` began; `until` is when it ends, in ms since the epoch: the time asked for, or
+ * for a duration the time the sleep started plus the duration, as the runtime saw it. Written
+ * for a time already past too, which waits not at all.
+ */
+ | {
+    type: "sleep.started";
+    node?: string;
+    /** The step's name: the one the call gave (`{ name }`), or `Sleep`; as for `op.called`. */
+    name?: string;
+    until: number;
+}
+/**
+ * A sandbox run seeded its fakes from the scenario named: each `Given` operation called
+ * through its fake, with what the fake returned, and each `Given` resource (by its type's id
+ * and its import id) put with its fields or removed (`gone`). Follows `run.started`.
+ */
+ | {
+    type: "scenario.seeded";
+    scenario: string;
+    seeds: ({
+        op: string;
+        input: unknown;
+        output: unknown;
+    } | {
+        resource: string;
+        name: string;
+        fields: Record<string, unknown>;
+    } | {
+        resource: string;
+        name: string;
+        gone: true;
+    })[];
+} | {
+    type: "run.finished";
+    output: unknown;
+}
+/** `error` as for `op.called`. */
+ | {
+    type: "run.failed";
+    error: ErrorInfo;
+});
+/**
+ * The `ctx.all` member a record was written in. `id` is `all:<seq>`, the run's next `seq` when
+ * the `ctx.all` began, so a replay names it the same; `index` is the member's position, `size`
+ * the member count and `node` the `ctx.all` call's outline node.
+ */
+export interface LedgerGroup {
+    id: string;
+    index: number;
+    size: number;
+    /** The outline node of the `ctx.all` call; as for `op.called`'s. */
+    node?: string;
+}
+/**
+ * The `ctx.all` member a call was made in. Each member runs inside `currentGroup.run`, and a
+ * queued call keeps the context it was queued in, so a call made outside the member meanwhile
+ * (one the workflow did not await) is not tagged as the member's.
+ */
+export declare const currentGroup: AsyncLocalStorage<LedgerGroup>;
+export interface LedgerStore {
+    /**
+     * Adds a record, unless one with the same id is already stored. A failed append is tried
+     * again, up to three times. A store throws an error with `retryable: false` for a failure
+     * that must not be retried because it would only happen again, such as a corrupt file or a
+     * record that can't be written as JSON.
+     */
+    append(record: LedgerRecord): Promise<void>;
+    /** A run's records in `seq` order. */
+    read(runId: string): Promise<LedgerRecord[]>;
+    /**
+     * Releases what the store holds (a connection pool), for good. Called by the one owner of the
+     * store: the worker's `stop` and `SanomaClient.close` close the Postgres store each made for a
+     * config without a `ledger` (`ownedLedger`); a store a config gives is its own to close.
+     */
+    close?(): Promise<void>;
+}
+/** The store a worker or client runs on, and `close`, which ends it only when it was made for them. */
+export interface OwnedLedger {
+    store: LedgerStore;
+    close(): Promise<void>;
+}
+/**
+ * The config's `ledger`, which stays the config's to close, or `postgresLedger` on its database,
+ * made here for the caller, and so the caller's to close: the worker and the client each make
+ * their own, and close it with themselves. Two of them on one database share the table, not a pool.
+ */
+export declare function ownedLedger(config: {
+    ledger?: LedgerStore;
+    databaseUrl: string;
+}): OwnedLedger;
+/**
+ * Keeps each run's records in `<dir>/<runId>.jsonl`, one JSON object per line. A run with no
+ * file, or a directory not yet created, reads as no records.
+ *
+ * A line with no newline at the end of a file is a write that was cut off (the process
+ * died mid-append): reads ignore it, and the next append removes it before writing.
+ * A line that isn't JSON anywhere else is corruption, and reads throw.
+ */
+export declare function jsonlLedger(dir: string): LedgerStore;
+/**
+ * Keeps records in the `sanoma_ledger` table of the database at `databaseUrl`, beside DBOS's
+ * tables: the default store, which the worker, the app and the client share through Postgres.
+ * The database and the table are made on first use when they are not there (`prepareDatabase`).
+ * The pool is opened on first use and ended by `close()`, after which the store refuses use.
+ */
+export declare function postgresLedger(databaseUrl: string): LedgerStore & {
+    close(): Promise<void>;
+};
+/** Keeps records in memory, for tests. */
+export declare function memoryLedger(): LedgerStore;
+type Common = "v" | "app" | "id" | "runId" | "seq" | "at" | "actor" | "workflow" | "group";
+/** What one kind of record says, without what every record carries: `type` and its own fields. */
+export type LedgerBody = LedgerRecord extends infer R ? (R extends LedgerRecord ? Omit<R, Common> : never) : never;
+/** A record of the run, with the next `seq` unless one is given, tagged with the `ctx.all` member it is written in. */
+export declare function entry(run: Run, body: LedgerBody, opts?: {
+    seq?: number;
+    key?: string;
+    at?: number;
+}): LedgerRecord;
+export declare function write(run: Run, record: LedgerRecord): Promise<void>;
+/**
+ * Records a failure. If the ledger fails too, throws both, so neither is lost, with the
+ * original's code: the run still fails the way it did.
+ */
+export declare function writeFailure(run: Run, record: LedgerRecord, original: unknown): Promise<void>;
+/** Says that a record was deliberately not written, and why. */
+export declare function skipped(record: LedgerRecord, why: string): void;
+export {};

package/dist/ledger.js

@@ -0,0 +1,251 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { appendFile, mkdir, readFile, truncate } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { isDeepStrictEqual } from "node:util";
+import { LEDGER_TABLE as TABLE, lazyPool, pgCode } from "./db.js";
+import { isFinal, keepCode } from "./errors.js";
+import { shown, warn } from "./log.js";
+import { errorMessage } from "./shared.js";
+/**
+ * The `ctx.all` member a call was made in. Each member runs inside `currentGroup.run`, and a
+ * queued call keeps the context it was queued in, so a call made outside the member meanwhile
+ * (one the workflow did not await) is not tagged as the member's.
+ */
+export const currentGroup = new AsyncLocalStorage();
+/**
+ * The config's `ledger`, which stays the config's to close, or `postgresLedger` on its database,
+ * made here for the caller, and so the caller's to close: the worker and the client each make
+ * their own, and close it with themselves. Two of them on one database share the table, not a pool.
+ */
+export function ownedLedger(config) {
+    if (config.ledger)
+        return { store: config.ledger, close: async () => undefined };
+    const store = postgresLedger(config.databaseUrl);
+    return { store, close: () => store.close() };
+}
+const bySeq = (a, b) => a.seq - b.seq;
+/** An error that trying again would only repeat. */
+const final = (message, cause) => Object.assign(new Error(message, { cause }), { retryable: false });
+/** JSON for a record, or an error that names the record when it can't be written as JSON (a BigInt, a cycle). */
+function serialize(record) {
+    try {
+        return JSON.stringify(record);
+    }
+    catch (cause) {
+        const op = record.type === "op.called" ? ` (${record.op})` : "";
+        throw final(`Ledger record ${record.id}${op} can't be written as JSON: ${errorMessage(cause)}`, cause);
+    }
+}
+/** The line `jsonlLedger` writes for a record: its JSON and a newline. */
+const lineOf = (record) => `${serialize(record)}\n`;
+const COMPARED = ["type", "input", "decision", "error", "output"];
+/**
+ * The first record with an id stands. Says so when a later one with that id differs where it
+ * matters, showing both, so a replay that went another way can be told from a retry. Compared
+ * as values, not text: a store may give the kept record's keys back in another order (`jsonb`).
+ */
+function warnIfDifferent(stored, line) {
+    const later = JSON.parse(line);
+    const differs = COMPARED.flatMap((k) => {
+        const kept = stored[k];
+        const sent = later[k];
+        return isDeepStrictEqual(kept, sent) ? [] : [`${k} (kept ${shown(kept, 200)}, later ${shown(sent, 200)})`];
+    });
+    if (differs.length) {
+        warn(`ledger: kept the first record ${stored.id}; a later write differed in ${differs.join("; ")}`);
+    }
+}
+/** The file's complete records, and the length of its complete lines when a cut-off line follows them. */
+async function load(path) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return { records: [] };
+        throw err;
+    }
+    const complete = text.slice(0, text.lastIndexOf("\n") + 1);
+    const records = [];
+    complete.split("\n").forEach((line, i) => {
+        if (!line.trim())
+            return;
+        try {
+            records.push(JSON.parse(line));
+        }
+        catch (cause) {
+            throw final(`${path}:${i + 1}: corrupt ledger line`, cause);
+        }
+    });
+    return complete.length < text.length ? { records, tornAt: Buffer.byteLength(complete) } : { records };
+}
+/**
+ * Keeps each run's records in `<dir>/<runId>.jsonl`, one JSON object per line. A run with no
+ * file, or a directory not yet created, reads as no records.
+ *
+ * A line with no newline at the end of a file is a write that was cut off (the process
+ * died mid-append): reads ignore it, and the next append removes it before writing.
+ * A line that isn't JSON anywhere else is corruption, and reads throw.
+ */
+export function jsonlLedger(dir) {
+    const root = resolve(dir);
+    const file = (runId) => join(root, `${encodeURIComponent(runId)}.jsonl`);
+    // Appends to one file are serialized, so the id check and the write can't interleave.
+    const queues = new Map();
+    return {
+        append(record) {
+            const path = file(record.runId);
+            const next = (queues.get(path) ?? Promise.resolve())
+                .catch(() => { })
+                .then(async () => {
+                const line = lineOf(record);
+                const { records, tornAt } = await load(path);
+                const stored = records.find((r) => r.id === record.id);
+                if (stored)
+                    return warnIfDifferent(stored, line);
+                await mkdir(root, { recursive: true });
+                if (tornAt !== undefined) {
+                    warn(`ledger: ${path} ended in a cut-off line; removed it before appending ${record.id}`);
+                    await truncate(path, tornAt);
+                }
+                await appendFile(path, line);
+            });
+            queues.set(path, next);
+            const forget = () => {
+                if (queues.get(path) === next)
+                    queues.delete(path);
+            };
+            next.then(forget, forget);
+            return next;
+        },
+        async read(runId) {
+            const path = file(runId);
+            await queues.get(path)?.catch(() => { });
+            // A missing directory, like a missing file, means nothing has been recorded there yet:
+            // `load` reads either as no records. Any other failure is thrown.
+            // A case-insensitive file system can map two run ids to one file.
+            return (await load(path)).records.filter((r) => r.runId === runId).toSorted(bySeq);
+        },
+    };
+}
+/** Postgres's class for a value it cannot store (a string with a NUL in `jsonb`): trying again would only repeat it. */
+const DATA_EXCEPTION = /^22/;
+/**
+ * Keeps records in the `sanoma_ledger` table of the database at `databaseUrl`, beside DBOS's
+ * tables: the default store, which the worker, the app and the client share through Postgres.
+ * The database and the table are made on first use when they are not there (`prepareDatabase`).
+ * The pool is opened on first use and ended by `close()`, after which the store refuses use.
+ */
+export function postgresLedger(databaseUrl) {
+    const pool = lazyPool(databaseUrl, "ledger");
+    return {
+        async append(record) {
+            const line = lineOf(record);
+            const conn = await pool.db();
+            const inserted = await conn
+                .query(`INSERT INTO ${TABLE} (id, run_id, seq, record) VALUES ($1, $2, $3, $4::jsonb) ON CONFLICT (id) DO NOTHING RETURNING n`, [record.id, record.runId, record.seq, line])
+                .catch((err) => {
+                if (DATA_EXCEPTION.test(pgCode(err))) {
+                    throw final(`Ledger record ${record.id} can't be stored: ${errorMessage(err)}`, err);
+                }
+                throw err;
+            });
+            if (inserted.rows.length)
+                return;
+            // Another write of the id was first: the record it stored stands.
+            const { rows } = await conn.query(`SELECT record FROM ${TABLE} WHERE id = $1`, [
+                record.id,
+            ]);
+            if (rows[0])
+                warnIfDifferent(rows[0].record, line);
+        },
+        async read(runId) {
+            const { rows } = await (await pool.db()).query(`SELECT record FROM ${TABLE} WHERE run_id = $1 ORDER BY seq, n`, [runId]);
+            // In seq order, as the other stores read; two records of one seq in write order.
+            return rows.map((r) => r.record);
+        },
+        close: pool.close,
+    };
+}
+/** Keeps records in memory, for tests. */
+export function memoryLedger() {
+    const runs = new Map();
+    return {
+        async append(record) {
+            const line = serialize(record);
+            let run = runs.get(record.runId);
+            if (!run)
+                runs.set(record.runId, (run = new Map()));
+            const stored = run.get(record.id);
+            if (stored)
+                warnIfDifferent(stored, line);
+            else
+                run.set(record.id, JSON.parse(line));
+        },
+        async read(runId) {
+            return [...(runs.get(runId)?.values() ?? [])].map((r) => structuredClone(r)).toSorted(bySeq);
+        },
+    };
+}
+/** A record of the run, with the next `seq` unless one is given, tagged with the `ctx.all` member it is written in. */
+export function entry(run, body, opts = {}) {
+    const seq = opts.seq ?? run.seq++;
+    const record = {
+        v: 1,
+        app: run.state.app,
+        id: `${run.id}:${body.type}:${opts.key ?? seq}`,
+        runId: run.id,
+        seq,
+        at: opts.at ?? Date.now(),
+        actor: run.actor,
+        workflow: run.workflow,
+        ...body,
+    };
+    const group = currentGroup.getStore();
+    if (group)
+        record.group = group;
+    return record;
+}
+// Waits between tries of a failed append. Safe to repeat: append is idempotent by id.
+const RETRY_DELAYS_MS = [50, 200, 800];
+async function append(run, record) {
+    for (let i = 0;; i++) {
+        try {
+            return await run.state.ledger.append(record);
+        }
+        catch (err) {
+            const wait = RETRY_DELAYS_MS[i];
+            if (wait === undefined || isFinal(err))
+                throw err;
+            warn(`ledger: appending ${record.id} failed (${errorMessage(err)}); trying again in ${wait} ms`);
+            await delay(wait);
+        }
+    }
+}
+/*
+ * Every ledger write happens outside DBOS steps. When DBOS replays a run after a restart,
+ * it re-runs the workflow function and these writes happen again with the same ids, so
+ * the store keeps one of each and fills in any the interrupted run never got to write.
+ */
+export async function write(run, record) {
+    await append(run, record);
+}
+/**
+ * Records a failure. If the ledger fails too, throws both, so neither is lost, with the
+ * original's code: the run still fails the way it did.
+ */
+export async function writeFailure(run, record, original) {
+    try {
+        await append(run, record);
+    }
+    catch (ledgerError) {
+        throw keepCode(new AggregateError([original, ledgerError], `${errorMessage(original)} (and the ledger could not record ${record.id}: ${errorMessage(ledgerError)})`, { cause: ledgerError }), original);
+    }
+}
+/** Says that a record was deliberately not written, and why. */
+export function skipped(record, why) {
+    warn(`did not write ${record.type} ${record.id}: ${why}`);
+}
+//# sourceMappingURL=ledger.js.map

package/dist/ledger.js.map

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

package/dist/lint.d.ts

@@ -0,0 +1,32 @@
+import { type LintProblem, type SourceFile } from "./ast.ts";
+export type { LintProblem } from "./ast.ts";
+/**
+ * Checks a workflow or policy file. Imports allowed: the names in `WORKFLOW_IMPORTS` and any
+ * type from `@sanoma-ai/workflows` or `sanoma`, `@sanoma-ai/connector-<vendor>`, `zod`, and relative files. With
+ * `filename`, a relative import must stay inside the file's nearest `workflows/` or `policies/`
+ * directory, or its own directory when it has neither. No `instanceof` against the runtime's
+ * error classes: read `errorCode(err)`.
+ *
+ * In each workflow's `run` (the literal `defineWorkflow` is called with), it reports what the
+ * outline cannot draw, as the worker refuses to start with (`outlineBody`): `ctx` used other
+ * than called directly (passed on, aliased, destructured), a function defined in `run` that uses
+ * `ctx` where the outline does not read it, `ctx` in a `finally`, a step name that is no literal
+ * and two calls with one step name, and in `run` and the callbacks it reads, a `return` before
+ * the end, a `throw` outside a `catch`, a `break` out of a loop and `continue`. Each message
+ * names what to write instead.
+ *
+ * It guards against accidental non-determinism and accidental ways around the policy; it is
+ * not a sandbox, and code written to get around it can.
+ */
+export declare function lintWorkflow(source: string, filename?: string): LintProblem[];
+/** The same, over a file `readSource` read: the reading `describeConfig` shares with the outline. */
+export declare function lintWorkflow(file: SourceFile): LintProblem[];
+/**
+ * Checks a data file under `resources/`: only named imports (a connector's constructors from its
+ * `…/resources` entry, and resources from other data files inside the same `resources/`
+ * directory), `export const <name> = <vendor>.<type>({ … })` with literal fields and names of
+ * declared resources, and `export default [ … ]`. Each message says what to write instead.
+ * It is the subset `readResources` reads (`readDataFile`), without the config: whether the
+ * connector, the type and the values are known is the reader's to say.
+ */
+export declare function lintResources(source: string, filename: string): LintProblem[];