@prestack/thread 0.0.1

package/dist/operations/nodes.js

@@ -0,0 +1,15 @@
+export const STOPPED = Symbol.for('thread.operation.stopped');
+export function stopped(thrown) {
+    if (typeof thrown !== 'object' || thrown === null)
+        return undefined;
+    if (thrown[STOPPED] !== true)
+        return undefined;
+    return { value: thrown.value };
+}
+export const nd_read = (block) => ({ type: 'nd_read' });
+export const nd_action = (block) => ({ type: 'nd_action' });
+export const nd_branch = (choose, ways) => ({ type: 'nd_branch' });
+export const nd_each = (over, block) => ({ type: 'nd_each' });
+export const nd_parallel = (blocks) => ({ type: 'nd_parallel' });
+export const nd_repeat = (ceiling, block) => ({ type: 'nd_repeat' });
+export const nd_stop = (block) => ({ type: 'nd_stop' });

package/dist/operations/operations.d.ts

@@ -0,0 +1,18 @@
+import type { z } from 'zod';
+import type { Member } from '../core/thread.ts';
+import type { Handed, Row, Supplied } from './seams.ts';
+export declare const OPERATIONS_FILE = "operations.ts";
+export declare const TRIALS_AT = "operations/_trials.json";
+export declare const NODES_FILE = "nodes.ts";
+export declare const MEMBERS_LIST = "MEMBERS";
+export interface Operation<I = unknown, R extends string = Supplied> {
+    readonly id: string;
+    readonly input: z.ZodType<I>;
+    readonly requires: readonly string[];
+    readonly run: (hands: Handed<R>, held: {
+        readonly input: I;
+    } & Readonly<Record<string, unknown>>) => Promise<unknown>;
+    readonly estimate: number;
+    readonly resource: (input: I) => Row | null;
+}
+export declare const OPERATIONS: readonly Member[];

package/dist/operations/operations.js

@@ -0,0 +1,5 @@
+export const OPERATIONS_FILE = 'operations.ts';
+export const TRIALS_AT = 'operations/_trials.json';
+export const NODES_FILE = 'nodes.ts';
+export const MEMBERS_LIST = 'MEMBERS';
+export const OPERATIONS = [];

package/dist/operations/queue-policy.d.ts

@@ -0,0 +1,3 @@
+export declare const MAX_ATTEMPTS = 5;
+export declare function backoffMs(attempts: number): number;
+export declare function isExhausted(attempts: number): boolean;

package/dist/operations/queue-policy.js

@@ -0,0 +1,8 @@
+export const MAX_ATTEMPTS = 5;
+export function backoffMs(attempts) {
+    const base = 1_000 * 2 ** Math.max(0, attempts - 1);
+    return Math.min(base, 5 * 60_000);
+}
+export function isExhausted(attempts) {
+    return attempts >= MAX_ATTEMPTS;
+}

package/dist/operations/result.d.ts

@@ -0,0 +1,19 @@
+import type { ErrorCode, ErrorDef } from './errors/catalog.ts';
+import type { ErrorClass } from './errors/classes.ts';
+export type ResultCode = 'denied' | 'invalid' | 'rate_limited' | 'feature_denied' | 'quota_exceeded' | 'error';
+export type FailureIdentity = Pick<ErrorDef, 'code' | 'class'>;
+export type Result<O> = {
+    ok: true;
+    value: O;
+} | {
+    ok: false;
+    code: ResultCode;
+    error: string;
+    because?: string;
+    errorCode?: ErrorCode;
+    errorClass?: ErrorClass;
+};
+export declare const ok: <O>(value: O) => Result<O>;
+export declare const fail: <O>(code: ResultCode, error: string, because?: string, identity?: FailureIdentity) => Result<O>;
+export declare class ValidationError extends Error {
+}

package/dist/operations/result.js

@@ -0,0 +1,10 @@
+export const ok = (value) => ({ ok: true, value });
+export const fail = (code, error, because, identity) => ({
+    ok: false,
+    code,
+    error,
+    because,
+    ...(identity === undefined ? {} : { errorCode: identity.code, errorClass: identity.class }),
+});
+export class ValidationError extends Error {
+}

package/dist/operations/seams.d.ts

@@ -0,0 +1,239 @@
+import type { Actor } from '../core/actor.ts';
+export type { FieldList, ReadField, Row, Store } from './store.ts';
+import type { Row, Store } from './store.ts';
+export interface Span {
+    ok(): void;
+    error(e: unknown): void;
+    end(): void;
+}
+export interface Telemetry {
+    start(action: string, run: string, tags: Record<string, unknown>): Span;
+    record?(span: {
+        readonly key: string;
+        readonly traceId: string;
+        readonly spanId: string;
+        readonly durationMs: number;
+        readonly ok: boolean;
+        readonly attrs?: Record<string, unknown>;
+        readonly actor?: Actor;
+        readonly nodeId?: string;
+        readonly workflowId?: string;
+        readonly error?: string;
+    }): void;
+}
+export type PropertyValue = string | number | boolean | null | readonly (string | number | boolean)[];
+export type LogLevel = 'info' | 'warn' | 'error';
+export interface Log {
+    write(level: LogLevel, action: string, actor: Actor, data: Record<string, unknown>): void;
+}
+export interface AuditRecord {
+    readonly action: string;
+    readonly outcome: AuditOutcome;
+    readonly subject: {
+        type: string;
+        id: string;
+    };
+    readonly changed?: readonly string[];
+    readonly because?: string;
+}
+export interface Audit {
+    append(actor: Actor, record: AuditRecord): Promise<void>;
+}
+export interface ErrorRecord {
+    readonly code: string;
+    readonly class: string;
+    readonly action: string;
+    readonly because?: string;
+}
+export interface Errors {
+    record(actor: Actor, error: ErrorRecord): Promise<void>;
+}
+export interface Search {
+    index(actor: Actor, entity: string, row: Row): Promise<void>;
+    query(actor: Actor, entity: string, q: string): Promise<Row[]>;
+}
+export interface Views {
+    query<T = Record<string, unknown>>(actor: Actor, sql: string, params: readonly unknown[]): Promise<readonly T[]>;
+}
+export interface Cost {
+    meter(action: string, actor: Actor, units?: number): void;
+}
+export interface Idempotency {
+    check(key: string | undefined, action: string): Promise<unknown | null>;
+    store(key: string | undefined, action: string, output: unknown): Promise<void>;
+}
+export interface PlatformEvent {
+    kind: string;
+    entity?: string;
+    id?: string;
+    run?: string;
+    actor: string | null;
+    at: number;
+    payload?: Readonly<Record<string, unknown>>;
+}
+export interface EventBus {
+    publish(event: PlatformEvent): Promise<void>;
+}
+export interface RateLimiter {
+    check(actor: Actor, action: string, operation?: string): Promise<boolean>;
+    checkPolicy(actor: Actor, policy: string): Promise<boolean>;
+}
+export interface FeatureGate {
+    check(actor: Actor, feature: string): Promise<boolean>;
+}
+export interface QuotaHold {
+    readonly ok: boolean;
+    readonly behavior: string | null;
+    readonly retryAfterSeconds: number;
+    commit(actual: number): Promise<void>;
+    release(): Promise<void>;
+}
+export interface Quotas {
+    reserve(actor: Actor, meter: string, estimate: number): Promise<QuotaHold>;
+    lower?(actor: Actor, meter: string, amount: number): Promise<void>;
+}
+export interface Outbox {
+    emit(actor: Actor, event: PlatformEvent): Promise<void>;
+}
+export interface Transactional {
+    transaction<T>(actor: Actor, fn: () => Promise<T>): Promise<T>;
+}
+export declare function isTransactional(store: Store): store is Store & Transactional;
+export interface Job<T = unknown> {
+    id: string;
+    kind: string;
+    payload: T;
+    attempts: number;
+    actor: Actor;
+}
+export interface EnqueueOpts {
+    runAt?: number;
+    dedupeKey?: string;
+}
+export interface SchedulerSeam {
+    readonly endpoint: string;
+    readonly secret: string;
+    register(app: {
+        id: string;
+        endpoint: string;
+        secret: string;
+    }): Promise<void>;
+    schedule(call: {
+        appId: string;
+        runAt: Date;
+        reason: string;
+        runId?: string;
+        dedupeKey?: string;
+    }): Promise<string>;
+    cancelForRun(appId: string, runId: string): Promise<void>;
+}
+export interface Queue {
+    enqueue<T>(actor: Actor, kind: string, payload: T, opts?: EnqueueOpts): Promise<string>;
+    poll(kinds: string[], limit: number, now: number): Promise<Job[]>;
+    ack(id: string): Promise<void>;
+    fail(id: string, error: string, now: number): Promise<void>;
+    deadLetter(id: string, error: string): Promise<void>;
+    deadLetters(): Promise<Job[]>;
+}
+export interface Files {
+    put(actor: Actor, key: string, body: Uint8Array, contentType: string): Promise<{
+        size: number;
+    }>;
+    get(actor: Actor, key: string): Promise<{
+        body: Uint8Array;
+        contentType: string;
+    } | null>;
+    signedUrl(actor: Actor, key: string, expiresInSeconds: number): Promise<string>;
+    remove(actor: Actor, key: string): Promise<void>;
+}
+export interface Clock {
+    now(): number;
+}
+export interface Random {
+    next(): number;
+    uuid(): string;
+}
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export interface HttpRequest {
+    readonly target: string;
+    readonly address: string;
+    readonly method: HttpMethod;
+    readonly path: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: Uint8Array;
+    readonly contentType?: string;
+    readonly idempotencyKey?: string;
+}
+export interface HttpResponse {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: Uint8Array;
+    readonly bytesSent: number;
+    readonly bytesReceived: number;
+    readonly durationMs: number;
+}
+export interface Http {
+    call(request: HttpRequest): Promise<HttpResponse>;
+}
+export interface Vault {
+    resolve(refs: readonly string[]): Promise<Readonly<Record<string, string>>>;
+}
+export interface Seams {
+    store: Store;
+    search: Search;
+    events: EventBus;
+    queue: Queue;
+    telemetry?: Telemetry;
+    log: Log;
+    audit: Audit;
+    errors: Errors;
+    cost?: Cost;
+    idempotency?: Idempotency;
+    rateLimiter?: RateLimiter;
+    flush?: () => Promise<void>;
+    scheduler?: SchedulerSeam;
+    featureGate?: FeatureGate;
+    permits?: {
+        check(actor: Actor, action: string, resource: Row | null): Promise<{
+            readonly allow: boolean;
+            readonly because?: string;
+        }>;
+    };
+    quotas?: Quotas;
+    outbox?: Outbox;
+    drainKick?: () => void;
+    vault?: Vault;
+    views?: Views;
+    clock: Clock;
+    random: Random;
+    files?: Files;
+    http?: Http;
+}
+export type AuditOutcome = 'ok' | 'denied' | 'rate_limited' | 'failed' | 'feature_denied' | 'quota_exceeded';
+export declare function isRow(v: unknown): v is Row;
+export declare const SUPPLY: {
+    readonly sm_store: "store";
+    readonly sm_search: "search";
+    readonly sm_queue: "queue";
+    readonly sm_events: "events";
+    readonly sm_clock: "clock";
+    readonly sm_random: "random";
+    readonly sm_vault: "vault";
+    readonly sm_views: "views";
+    readonly sm_files: "files";
+};
+export type Supplied = keyof typeof SUPPLY;
+export declare const SUPPLIES: readonly Supplied[];
+export declare const supplies: (one: string) => one is Supplied;
+export type Handed<R extends string = Supplied> = {
+    readonly actor: Actor;
+} & {
+    readonly [K in R as K extends Supplied ? (typeof SUPPLY)[K] : K]: K extends Supplied ? NonNullable<Seams[(typeof SUPPLY)[K]]> : Readonly<Record<string, (given?: {
+        readonly fills?: Readonly<Record<string, string | number>>;
+        readonly json?: unknown;
+        readonly body?: Uint8Array;
+        readonly contentType?: string;
+    }) => Promise<HttpResponse>>>;
+};
+export type Reads<H> = Pick<H, Extract<keyof H, 'actor' | 'store' | 'search' | 'views'>>;
+export declare const SAID: Readonly<Record<keyof Seams, string>>;

package/dist/operations/seams.js

@@ -0,0 +1,45 @@
+export function isTransactional(store) {
+    return typeof store.transaction === 'function';
+}
+export function isRow(v) {
+    return typeof v === 'object' && v !== null && typeof v.id === 'string';
+}
+export const SUPPLY = {
+    sm_store: 'store',
+    sm_search: 'search',
+    sm_queue: 'queue',
+    sm_events: 'events',
+    sm_clock: 'clock',
+    sm_random: 'random',
+    sm_vault: 'vault',
+    sm_views: 'views',
+    sm_files: 'files',
+};
+export const SUPPLIES = Object.keys(SUPPLY);
+export const supplies = (one) => one in SUPPLY;
+export const SAID = {
+    store: 'where rows are kept: insert, get, list, update and remove, bound to whoever asked',
+    search: 'indexing a row and querying an index, for what cannot be found by id',
+    events: 'announcing that something happened, to whoever is listening',
+    queue: 'handing work to something else to run later',
+    telemetry: 'the span opened around every run, and where it is recorded',
+    log: 'the line written for every run: its outcome, who was allowed, what it spent',
+    audit: 'the record of what was done, by whom, to what',
+    errors: 'the record of every failure, by code and class',
+    cost: 'metering what a run spent',
+    idempotency: 'remembering an answer under its key, so a repeated request is answered once',
+    rateLimiter: 'refusing a caller who asks too often',
+    flush: 'what runs when the process is about to stop, so nothing buffered is lost',
+    scheduler: 'registering this app with a scheduler and booking a later run',
+    featureGate: 'refusing an operation the caller\'s plan does not include',
+    permits: 'the gate every operation passes: who may ask for what, from the grants',
+    quotas: 'reserving what a run may spend before it starts, and settling it after',
+    outbox: 'events written with the transaction and published after it commits',
+    drainKick: 'nudging the queue worker that work has arrived',
+    vault: 'opening a secret by name at the moment of use',
+    views: 'reading through a declared view rather than a table',
+    clock: 'the current time',
+    random: 'randomness: a number, a uuid',
+    files: 'putting a file somewhere, fetching one back, handing out a signed link to one',
+    http: 'how a call leaves the process, and what it comes back with',
+};

package/dist/operations/store.d.ts

@@ -0,0 +1,14 @@
+import type { Actor } from '../core/actor.ts';
+export type Row = Record<string, unknown>;
+export type ReadField = `fld_${string}` | `rel_${string}` | (string & {});
+export type FieldList = readonly [ReadField, ...ReadField[]];
+export interface Store {
+    insert(actor: Actor, entity: string, row: Row): Promise<Row>;
+    get(actor: Actor, entity: string, key: string | number, fields: FieldList): Promise<Row | null>;
+    list(actor: Actor, entity: string, opts?: {
+        limit?: number;
+        where?: Readonly<Record<string, string | number | boolean | null>>;
+    }): Promise<Row[]>;
+    update(actor: Actor, entity: string, key: string | number, patch: Record<string, unknown>, expectedVersion?: number): Promise<Row>;
+    remove(actor: Actor, entity: string, key: string | number): Promise<void>;
+}

package/dist/operations/store.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@prestack/thread",
+  "version": "0.0.1",
+  "type": "module",
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./*": "./dist/*.js"
+  },
+  "bin": {
+    "thread": "dist/core/cli.js"
+  }
+}