@prestack/thread 0.0.1 → 0.0.3

package/dist/operations/seams.ts

@@ -0,0 +1,364 @@
+import type { Actor } from '../core/actor.ts'
+
+export type { FieldList, ReadField, Row, Store } from './store.ts'
+
+import type { FieldList, 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 function isTransactional(store: Store): store is Store & Transactional {
+  return typeof (store as Partial<Transactional>).transaction === 'function'
+}
+
+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 function isRow(v: unknown): v is Row {
+  return typeof v === 'object' && v !== null && typeof (v as { id?: unknown }).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',
+} as const satisfies Readonly<Record<string, keyof Seams>>
+
+export type Supplied = keyof typeof SUPPLY
+
+export const SUPPLIES: readonly Supplied[] = Object.keys(SUPPLY) as readonly Supplied[]
+
+export const supplies = (one: string): one is Supplied => one in SUPPLY
+
+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 const SAID: Readonly<Record<keyof Seams, string>> = {
+  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.ts

@@ -0,0 +1,29 @@
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prestack/thread",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "type": "module",
   "files": [
     "dist",
@@ -12,5 +12,12 @@
   },
   "bin": {
     "thread": "dist/core/cli.js"
+  },
+  "dependencies": {
+    "esbuild": "^0.28.2",
+    "eslint": "^10.9.1",
+    "typescript": "^6.0.0",
+    "typescript-eslint": "^8.68.0",
+    "zod": "^4.5.4"
   }
 }

package/dist/integrations/generators/sdk.d.ts

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

package/dist/integrations/generators/sdk.js

@@ -1,148 +0,0 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
-import { spawnSync } from 'node:child_process';
-import { readFileSync, writeFileSync } from 'node:fs';
-import { relative } from 'node:path';
-import { stdout } from 'node:process';
-import { generators } from "../../core/chain.js";
-import { exit } from "../../core/invoked.js";
-import { asking, given, nouns, refuse, slug, wordsIn } from "../../core/asking.js";
-import { listBounds, withRow } from "../../core/rows.js";
-import { named as packageOf } from "../../core/scope.js";
-import { findTree, inTree } from "../../core/tree.js";
-const TREE = findTree();
-const FILE = 'derivation.ts';
-const LIST = 'GENERATORS';
-const OWNER = 'integrations';
-const DECLARES = 'declares';
-const NAME = /^[a-z][a-z0-9_]*$/;
-const PACKAGE = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
-const PREFIX = 'sdk_';
-const here = (one) => relative(TREE.at, one).split('\\').join('/');
-const path = inTree(TREE, FILE);
-const at = here(path);
-import { quoted } from "../../core/rows.js";
-const words = wordsIn([]);
-const rows = await generators(TREE);
-const already = rows.filter((one) => typeof one.id === 'string' && one.id.startsWith(PREFIX));
-const first = words[0];
-if (first === undefined) {
-    stdout.write(already.length === 0
-        ? 'sdk: no SDK declared yet.\n'
-        : `sdk: ${String(already.length)} declared:\n${already
-            .map((one) => `  ${(one.by ?? '').slice('thread run '.length)} — ${one.describes ?? ''}`)
-            .join('\n')}\n`);
-    stdout.write('\nthread create sdk <name> — installs an npm package, asks what it is for and which declared secret it\n' +
-        'needs, and declares it. Then `thread run <name> <method>` calls it, resolving the credential through the\n' +
-        'vault at the moment of the call. `<method>` is dot-separated for a namespaced one, e.g. `customers.list`.\n');
-    exit(0);
-}
-const name = slug(first);
-if (name === '')
-    refuse('an SDK has to be called something — `thread create sdk <name>`');
-if (!NAME.test(name))
-    refuse(`"${name}" cannot be the name of an SDK — it is written in lower_snake_case`);
-const claimed = nouns(rows, 'run').get(name);
-if (claimed !== undefined) {
-    refuse(`\`thread run ${name}\` already resolves to ${claimed} — that name is taken`);
-}
-const { ask, shut } = asking(given());
-const npmPackage = (await ask('package', 'npm package to install: ')).trim();
-if (npmPackage === '') {
-    shut();
-    refuse('an SDK installs something — the npm package is what `npm install` is given');
-}
-if (!PACKAGE.test(npmPackage)) {
-    shut();
-    refuse(`"${npmPackage}" does not read as an npm package name`);
-}
-const describes = (await ask('describes', 'what is it for? ')).trim();
-if (describes === '') {
-    shut();
-    refuse('an SDK says what it is for — the sentence is what somebody reads before running it');
-}
-let secrets = [];
-try {
-    const taken = (await import(__rewriteRelativeImportExtension(new URL(`file://${inTree(TREE, 'secrets.ts')}`).href)));
-    secrets = taken.SECRETS ?? [];
-}
-catch {
-    secrets = [];
-}
-const carrying = (await ask('requires', `which secret does it need — ${secrets.map((one) => one.id).join(', ') || '(none declared yet)'}\n` +
-    '  If this SDK needs a url, a key, a token or a password to work, IT GOES HERE and nowhere else.\n' +
-    '  Declare it first with `thread create secret`, then name it here, comma-separated. It is resolved\n' +
-    '  through the vault at the moment of the call and is never written into any file.\n' +
-    '  Blank only if the SDK genuinely needs no credential at all — a declaration with the wrong answer\n' +
-    '  here does not fail now, it fails at the call with the vendor\'s own error.\n' +
-    '  > '))
-    .split(',')
-    .map((one) => one.trim())
-    .filter((one) => one !== '');
-shut();
-for (const one of carrying) {
-    if (!secrets.some((each) => each.id === one)) {
-        refuse(`\`${one}\` is not a secret this app declares. Declare it first with \`thread create secret\` — a credential is given to something that said it needed it, or not at all.`);
-    }
-}
-let text;
-try {
-    text = readFileSync(path, 'utf8');
-}
-catch {
-    refuse(`${at} could not be read. Attach \`${packageOf('derivation')}\` first — that is what writes it.`);
-}
-const where = listBounds(text, LIST);
-if (where === undefined)
-    refuse(`${at} states no \`${LIST}\` list to declare a generator in`);
-stdout.write(`sdk: installing ${npmPackage} …\n`);
-const installed = spawnSync('npm', ['install', npmPackage], { cwd: TREE.at, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
-if (installed.status !== 0) {
-    refuse(`\`npm install ${npmPackage}\` failed, so nothing was declared:\n${`${installed.stdout ?? ''}${installed.stderr ?? ''}`.trim()}`);
-}
-stdout.write(`sdk: installed ${npmPackage}.\n`);
-const fileAt = `_threads/sdk_${name}.ts`;
-const SOURCE = `import { run } from '../sdk.ts'
-
-await run({ name: ${quoted(name)}, module: ${quoted(npmPackage)}, requires: [${carrying.map(quoted).join(', ')}] })
-`;
-writeFileSync(inTree(TREE, `sdk_${name}.ts`), SOURCE, 'utf8');
-const row = [
-    '  {',
-    `    id: ${quoted(`${PREFIX}${name}`)},`,
-    `    at: ${quoted(fileAt)},`,
-    `    describes: ${quoted(describes)},`,
-    '    version: 1,',
-    `    by: ${quoted(`thread run ${name}`)},`,
-    ...(carrying.length === 0 ? [] : [`    requires: [${carrying.map(quoted).join(', ')}],`]),
-    '  },',
-].join('\n');
-writeFileSync(path, withRow(text, where, row), 'utf8');
-const owner = inTree(TREE, `${OWNER}.ts`);
-let owned = '';
-try {
-    owned = readFileSync(owner, 'utf8');
-}
-catch {
-    refuse(`${OWNER}.ts could not be read, so there is nothing to declare this under.`);
-}
-const under = listBounds(owned, DECLARES);
-if (under === undefined)
-    refuse(`${OWNER}.ts states no \`${DECLARES}\` list to declare this in`);
-writeFileSync(owner, withRow(owned, under, [
-    '  {',
-    `    id: ${quoted(`${PREFIX}${name}`)},`,
-    `    at: ${quoted(fileAt)},`,
-    `    describes: ${quoted(describes)},`,
-    '    version: 1,',
-    '  },',
-].join('\n')), 'utf8');
-stdout.write(`sdk: declared ${name} — ${npmPackage}, reached with \`thread run ${name} <method>\`. ` +
-    `${carrying.length === 0 ? 'It needs no secret.' : `It resolves ${carrying.join(', ')} through the vault at call time.`}\n`);
-exit(0);