pipework 0.8.2 → 0.8.5

package/dist/trace/check/io-pattern.d.ts

@@ -0,0 +1,14 @@
+import { type AstNode } from './flow-step-site.js';
+export type IoKind = 'read' | 'write';
+/**
+ * Classify `call` against the stock I/O registry and the optional consumer
+ * `extras` registry, or return `null` if the call is not I/O. `extras` is the
+ * `Record` shape `config.trace.io` resolves to — keys are lexical patterns
+ * (`"fetch"` or `"cache.get"`), values are `'read' | 'write'`.
+ *
+ * `call` must be a `CallExpression`; callers walk the AST and hand each one
+ * over. This function is pure over the node — no parent lookups, no type
+ * resolution. Lexical match only.
+ */
+export declare function classifyIo(call: AstNode, extras?: Readonly<Record<string, IoKind>>): IoKind | null;
+//# sourceMappingURL=io-pattern.d.ts.map

package/dist/trace/check/io-pattern.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"io-pattern.d.ts","sourceRoot":"","sources":["../../../src/trace/check/io-pattern.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAU,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAE1D,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAIrC;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,OAAO,EACb,MAAM,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,GAC5C,MAAM,GAAG,IAAI,CASf"}

package/dist/trace/check/io-pattern.js

@@ -0,0 +1,113 @@
+// The I/O call-target registry consumed by the Tier-2 coverage check. Given a
+// `CallExpression`, classifies it as a read, a write, or not-I/O.
+//
+// Stock list (pipework-owned, lexical):
+//   - Writes: `pipe.insert / pipe.update / pipe.delete / pipe.upsert /
+//     pipe.bulkSet`. These are the locked write entrypoints from Q8; the
+//     raw-write lint rule (component 13) backs them up.
+//   - Reads: any call whose callee chains off `pipe(...)` — e.g.
+//     `pipe('db').execute(...)`, `pipe(name).select(...)`,
+//     `pipe('db').query.users.findMany(...)`. The `pipe(name)` accessor only
+//     exists to perform I/O, so any method called on its result counts.
+//
+// Consumer extension (Q9): cache, external HTTP, queue publishes — anything
+// outside the stock list — is registered through `pipework.config.ts` under
+// `trace.io`. The registry is a `Record<string, 'read' | 'write'>` where the
+// key is a lexical call pattern: a bare identifier (`"fetch"`) matches an
+// identifier callee; an `"object.method"` pattern matches a single-level
+// member-access callee. The schema validator rejects anything more elaborate —
+// type resolution is out of scope, lexical matching is the contract.
+import { isNode } from './flow-step-site.js';
+const PIPE_WRITE_METHODS = new Set(['insert', 'update', 'delete', 'upsert', 'bulkSet']);
+/**
+ * Classify `call` against the stock I/O registry and the optional consumer
+ * `extras` registry, or return `null` if the call is not I/O. `extras` is the
+ * `Record` shape `config.trace.io` resolves to — keys are lexical patterns
+ * (`"fetch"` or `"cache.get"`), values are `'read' | 'write'`.
+ *
+ * `call` must be a `CallExpression`; callers walk the AST and hand each one
+ * over. This function is pure over the node — no parent lookups, no type
+ * resolution. Lexical match only.
+ */
+export function classifyIo(call, extras = {}) {
+    if (call.type !== 'CallExpression')
+        return null;
+    const callee = call['callee'];
+    if (!isNode(callee))
+        return null;
+    if (isPipeWriteCallee(callee))
+        return 'write';
+    if (chainsOffPipeAccessor(callee))
+        return 'read';
+    return matchExtras(callee, extras);
+}
+/** `pipe.<verb>` where `<verb>` is one of the locked write entrypoints. */
+function isPipeWriteCallee(callee) {
+    if (callee.type !== 'MemberExpression')
+        return false;
+    if (callee['computed'] === true)
+        return false;
+    const object = callee['object'];
+    const property = callee['property'];
+    if (!isNode(object) || object.type !== 'Identifier' || object['name'] !== 'pipe')
+        return false;
+    if (!isNode(property) || property.type !== 'Identifier')
+        return false;
+    const name = property['name'];
+    return typeof name === 'string' && PIPE_WRITE_METHODS.has(name);
+}
+/**
+ * The callee is a chain off `pipe(...)` — anywhere up the member-expression
+ * spine. `pipe('db').execute(sql)` matches; `pipe('db').query.users.findMany()`
+ * matches; `pipe.update(t)` (no call on `pipe`) does not.
+ */
+function chainsOffPipeAccessor(callee) {
+    let cursor = callee;
+    while (cursor.type === 'MemberExpression') {
+        const object = cursor['object'];
+        if (!isNode(object))
+            return false;
+        if (isPipeInvocation(object))
+            return true;
+        cursor = object;
+    }
+    return false;
+}
+/** `pipe(...)` — a call expression whose callee is the identifier `pipe`. */
+function isPipeInvocation(node) {
+    if (node.type !== 'CallExpression')
+        return false;
+    const callee = node['callee'];
+    return isNode(callee) && callee.type === 'Identifier' && callee['name'] === 'pipe';
+}
+/**
+ * Looks up `callee` against the consumer registry. Two shapes match:
+ *   - Identifier `foo` → key `"foo"`
+ *   - Non-computed MemberExpression `obj.method` (Identifier object,
+ *     Identifier property) → key `"obj.method"`
+ * Anything else falls through (returns `null`) — the stock registry has
+ * already exited above, so this is the not-I/O bucket.
+ */
+function matchExtras(callee, extras) {
+    if (callee.type === 'Identifier') {
+        const name = callee['name'];
+        if (typeof name !== 'string')
+            return null;
+        return extras[name] ?? null;
+    }
+    if (callee.type === 'MemberExpression' && callee['computed'] !== true) {
+        const object = callee['object'];
+        const property = callee['property'];
+        if (!isNode(object) || object.type !== 'Identifier')
+            return null;
+        if (!isNode(property) || property.type !== 'Identifier')
+            return null;
+        const objectName = object['name'];
+        const propertyName = property['name'];
+        if (typeof objectName !== 'string' || typeof propertyName !== 'string')
+            return null;
+        return extras[`${objectName}.${propertyName}`] ?? null;
+    }
+    return null;
+}
+//# sourceMappingURL=io-pattern.js.map

package/dist/trace/check/io-pattern.js.map

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

package/dist/trace/codemod/add-cardinality.d.ts

@@ -0,0 +1,38 @@
+export interface CardinalityFill {
+    /** 1-based file line of the `@downstream` tag the codemod filled. */
+    readonly line: number;
+    /** `path:symbol` target of the edge that received a cardinality. */
+    readonly target: string;
+    /** The cardinality that was appended. */
+    readonly kind: 'step' | 'branch';
+}
+export interface UnresolvedEdge {
+    /** 1-based file line of the `@downstream` tag the codemod left untouched. */
+    readonly line: number;
+    /** `path:symbol` target the codemod could not fill. */
+    readonly target: string;
+    /**
+     * - `ambiguous` — analyzer could not classify the edge; needs a human.
+     * - `non-trivial-form` — the `@downstream` declaration spans lines or
+     *   carries trailing text the codemod won't blindly rewrite.
+     */
+    readonly reason: 'ambiguous' | 'non-trivial-form';
+}
+export interface RewriteResult {
+    /** The rewritten source — strictly equal to the input when nothing changed. */
+    readonly text: string;
+    /** Every edge whose cardinality the codemod filled in. */
+    readonly fills: readonly CardinalityFill[];
+    /** Every edge the codemod left untouched but a human still needs to address. */
+    readonly unresolved: readonly UnresolvedEdge[];
+}
+/**
+ * Walks `source` for `@flow_step` sites, classifies each `@downstream` edge
+ * whose cardinality is missing, and returns the rewritten text plus a record
+ * of what was filled and what remains for the user.
+ *
+ * `source` must be parseable TypeScript. Files whose parse fails are the
+ * caller's concern — the codemod surfaces `collectFlowStepSites`'s throw.
+ */
+export declare function rewriteFlowCardinality(source: string): RewriteResult;
+//# sourceMappingURL=add-cardinality.d.ts.map

package/dist/trace/codemod/add-cardinality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-cardinality.d.ts","sourceRoot":"","sources":["../../../src/trace/codemod/add-cardinality.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAA;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,kBAAkB,CAAA;CAClD;AAED,MAAM,WAAW,aAAa;IAC5B,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAA;IAC1C,gFAAgF;IAChF,QAAQ,CAAC,UAAU,EAAE,SAAS,cAAc,EAAE,CAAA;CAC/C;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAoBpE"}

package/dist/trace/codemod/add-cardinality.js

@@ -0,0 +1,106 @@
+// The cardinality codemod (component 4). For every `@downstream path:symbol`
+// JSDoc line that omits its cardinality, classify the edge structurally and
+// append `step` or `branch`. Edges the analyzer cannot classify (indirection)
+// and edges declared on non-trivial textual forms (continuation lines) are
+// left untouched and reported as `unresolved` for the user to address by hand.
+//
+// Scope is deliberately narrow: the codemod only *fills blanks*. It never
+// rewrites an existing cardinality, never touches a method flow step (those
+// are banned by the `flow` check), and never re-flows the surrounding JSDoc.
+// Minimal churn — one token per line, in place.
+import { collectFlowStepSites } from '../check/flow-step-site.js';
+import { classifyEdge } from '../cardinality/classify-edge.js';
+/**
+ * Walks `source` for `@flow_step` sites, classifies each `@downstream` edge
+ * whose cardinality is missing, and returns the rewritten text plus a record
+ * of what was filled and what remains for the user.
+ *
+ * `source` must be parseable TypeScript. Files whose parse fails are the
+ * caller's concern — the codemod surfaces `collectFlowStepSites`'s throw.
+ */
+export function rewriteFlowCardinality(source) {
+    const sites = collectFlowStepSites(source);
+    if (sites.length === 0) {
+        return { text: source, fills: [], unresolved: [] };
+    }
+    const lineEnding = detectLineEnding(source);
+    const lines = source.split(/\r?\n/);
+    const replacements = new Map();
+    const fills = [];
+    const unresolved = [];
+    for (const site of sites) {
+        processSite(site, lines, replacements, fills, unresolved);
+    }
+    if (replacements.size === 0)
+        return { text: source, fills: [], unresolved };
+    const rewritten = lines.map((line, i) => replacements.get(i) ?? line);
+    return { text: rewritten.join(lineEnding), fills, unresolved };
+}
+function processSite(site, lines, replacements, fills, unresolved) {
+    // The `flow` check rejects invalid annotations, method shapes, and orphans
+    // as their own diagnostics — fixing them is the user's job. The codemod's
+    // only job is to fill missing cardinality on legal flow-step functions.
+    if (site.annotation.kind !== 'annotation')
+        return;
+    if (site.subject.shape !== 'function')
+        return;
+    const edges = site.annotation.annotation.downstream;
+    if (edges.length === 0)
+        return;
+    const blockStart = site.commentLine - 1;
+    const blockEnd = findBlockEnd(lines, blockStart);
+    // The parser produces one `DownstreamEdge` per `@downstream` tag in source
+    // order; scanning the JSDoc lines in the same order keeps the two streams
+    // aligned, so the Nth `@downstream` line corresponds to `edges[N]`.
+    let edgeIndex = -1;
+    for (let i = blockStart; i <= blockEnd; i++) {
+        const raw = lines[i];
+        if (raw === undefined)
+            continue;
+        if (!isDownstreamLine(raw))
+            continue;
+        edgeIndex++;
+        const edge = edges[edgeIndex];
+        if (edge === undefined)
+            continue;
+        if (edge.cardinality !== null)
+            continue;
+        const target = `${edge.path}:${edge.symbol}`;
+        const match = BARE_DOWNSTREAM.exec(raw);
+        if (match === null) {
+            unresolved.push({ line: i + 1, target, reason: 'non-trivial-form' });
+            continue;
+        }
+        const classification = classifyEdge('', site, edge);
+        if (classification.structural === 'ambiguous') {
+            unresolved.push({ line: i + 1, target, reason: 'ambiguous' });
+            continue;
+        }
+        const prefix = match[1] ?? '';
+        const targetText = match[2] ?? '';
+        replacements.set(i, `${prefix}${targetText} ${classification.structural}`);
+        fills.push({ line: i + 1, target, kind: classification.structural });
+    }
+}
+function findBlockEnd(lines, start) {
+    for (let i = start; i < lines.length; i++) {
+        if ((lines[i] ?? '').includes('*/'))
+            return i;
+    }
+    return lines.length - 1;
+}
+function detectLineEnding(source) {
+    return source.includes('\r\n') ? '\r\n' : '\n';
+}
+// Matches `@downstream path:symbol` on a line by itself (with optional JSDoc
+// leader and trailing whitespace). The capture groups preserve the prefix and
+// the target verbatim so the rebuilt line differs from the original only by a
+// trailing ` step` or ` branch`.
+const BARE_DOWNSTREAM = /^(\s*\*?\s*@downstream\s+)(\S+:\S+)\s*$/;
+// A weaker match used only to count `@downstream` lines so the codemod's
+// scanner stays aligned with the parser's edge ordering.
+const DOWNSTREAM_TAG = /^\s*\*?\s*@downstream\b/;
+function isDownstreamLine(text) {
+    return DOWNSTREAM_TAG.test(text);
+}
+//# sourceMappingURL=add-cardinality.js.map

package/dist/trace/codemod/add-cardinality.js.map

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

package/dist/trace/codemod/run.d.ts

@@ -0,0 +1,25 @@
+import { type CardinalityFill, type UnresolvedEdge } from './add-cardinality.js';
+export interface CodemodRunOptions {
+    readonly cwd: string;
+    readonly files: readonly string[];
+    /** When true, compute everything but do not write to disk. */
+    readonly dryRun: boolean;
+}
+export interface FileResult {
+    /** Source path relative to `cwd`. */
+    readonly file: string;
+    readonly fills: readonly CardinalityFill[];
+    readonly unresolved: readonly UnresolvedEdge[];
+    /** True when the codemod produced a different text than the input. */
+    readonly changed: boolean;
+}
+export interface CodemodRunResult {
+    /** One entry per file that had at least one fill or unresolved edge. */
+    readonly files: readonly FileResult[];
+    readonly totalFills: number;
+    readonly totalUnresolved: number;
+    readonly filesChanged: number;
+}
+/** Runs the cardinality codemod across `files`. Missing or unparseable files are skipped. */
+export declare function runFlowCardinalityCodemod(opts: CodemodRunOptions): CodemodRunResult;
+//# sourceMappingURL=run.d.ts.map

package/dist/trace/codemod/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/trace/codemod/run.ts"],"names":[],"mappings":"AAQA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAA;AAE7B,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAA;IAC1C,QAAQ,CAAC,UAAU,EAAE,SAAS,cAAc,EAAE,CAAA;IAC9C,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAA;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAC9B;AAED,6FAA6F;AAC7F,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,iBAAiB,GAAG,gBAAgB,CAwCnF"}

package/dist/trace/codemod/run.js

@@ -0,0 +1,47 @@
+// File-scanning wrapper around the cardinality codemod: reads each source
+// file, applies `rewriteFlowCardinality`, and writes the result back unless
+// `dryRun` is set. Mirrors `flow-check.ts`'s shape — file I/O lives here, the
+// rewrite logic stays pure in add-cardinality.ts.
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { rewriteFlowCardinality, } from './add-cardinality.js';
+/** Runs the cardinality codemod across `files`. Missing or unparseable files are skipped. */
+export function runFlowCardinalityCodemod(opts) {
+    const fileResults = [];
+    let totalFills = 0;
+    let totalUnresolved = 0;
+    let filesChanged = 0;
+    for (const file of opts.files) {
+        const abs = join(opts.cwd, file);
+        if (!existsSync(abs))
+            continue;
+        const source = readFileSync(abs, 'utf-8');
+        let rewrite;
+        try {
+            rewrite = rewriteFlowCardinality(source);
+        }
+        catch {
+            // A file the AST parser cannot read — leave its syntax errors to the
+            // type checker, exactly as `flow-check.ts` does.
+            continue;
+        }
+        if (rewrite.fills.length === 0 && rewrite.unresolved.length === 0)
+            continue;
+        const changed = rewrite.text !== source;
+        if (changed && !opts.dryRun) {
+            writeFileSync(abs, rewrite.text, 'utf-8');
+        }
+        fileResults.push({
+            file,
+            fills: rewrite.fills,
+            unresolved: rewrite.unresolved,
+            changed,
+        });
+        totalFills += rewrite.fills.length;
+        totalUnresolved += rewrite.unresolved.length;
+        if (changed)
+            filesChanged++;
+    }
+    return { files: fileResults, totalFills, totalUnresolved, filesChanged };
+}
+//# sourceMappingURL=run.js.map

package/dist/trace/codemod/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../../src/trace/codemod/run.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,4EAA4E;AAC5E,8EAA8E;AAC9E,kDAAkD;AAElD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACjE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEhC,OAAO,EACL,sBAAsB,GAGvB,MAAM,sBAAsB,CAAA;AA0B7B,6FAA6F;AAC7F,MAAM,UAAU,yBAAyB,CAAC,IAAuB;IAC/D,MAAM,WAAW,GAAiB,EAAE,CAAA;IACpC,IAAI,UAAU,GAAG,CAAC,CAAA;IAClB,IAAI,eAAe,GAAG,CAAC,CAAA;IACvB,IAAI,YAAY,GAAG,CAAC,CAAA;IAEpB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;QAChC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAQ;QAE9B,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;QAEzC,IAAI,OAAO,CAAA;QACX,IAAI,CAAC;YACH,OAAO,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAA;QAC1C,CAAC;QAAC,MAAM,CAAC;YACP,qEAAqE;YACrE,iDAAiD;YACjD,SAAQ;QACV,CAAC;QAED,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;YAAE,SAAQ;QAE3E,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,KAAK,MAAM,CAAA;QACvC,IAAI,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YAC5B,aAAa,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QAC3C,CAAC;QAED,WAAW,CAAC,IAAI,CAAC;YACf,IAAI;YACJ,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,OAAO;SACR,CAAC,CAAA;QACF,UAAU,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,CAAA;QAClC,eAAe,IAAI,OAAO,CAAC,UAAU,CAAC,MAAM,CAAA;QAC5C,IAAI,OAAO;YAAE,YAAY,EAAE,CAAA;IAC7B,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAE,YAAY,EAAE,CAAA;AAC1E,CAAC"}

package/dist/trace/entry/close-trace.d.ts

@@ -0,0 +1,7 @@
+import type { Manifold } from '../../core/pipework.js';
+import type { TraceContext } from './trace-context.js';
+/** How an entry ended — a clean return, or a thrown error. */
+export type TraceOutcome = 'closed' | 'error';
+/** Closes `ctx`'s trace row with `outcome` and flushes its step buffer. No-op when the entry ran untraced. */
+export declare function closeTrace(instance: Manifold, ctx: TraceContext | null, outcome: TraceOutcome): Promise<void>;
+//# sourceMappingURL=close-trace.d.ts.map

package/dist/trace/entry/close-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"close-trace.d.ts","sourceRoot":"","sources":["../../../src/trace/entry/close-trace.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAOtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD,8DAA8D;AAC9D,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,OAAO,CAAA;AAE7C,8GAA8G;AAC9G,wBAAgB,UAAU,CACxB,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,YAAY,GAAG,IAAI,EACxB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAiCf"}

package/dist/trace/entry/close-trace.js

@@ -0,0 +1,54 @@
+// Closes the `trace` row an entry opened: stamps the final status and the
+// close time, and flushes the in-memory `trace_step` buffer in the same beat.
+// Like the open, the write is fire-and-forget and never throws — but it first
+// waits on `persisted`, so neither the closing `UPDATE` nor the step `INSERT`s
+// can outrun the opening `INSERT` and miss the row.
+//
+// A truncated trace (Q7) keeps its `truncated` status here: `truncateTrace`
+// already settled the cap-blowing path, and `closeTrace` running last must not
+// downgrade a casualty to `closed` / `error`. The buffer drain is still safe —
+// `truncateTrace` already drained it, and `__flowStep` records nothing after
+// truncation, so `drain()` returns the empty array.
+//
+// The returned promise settles once the `UPDATE` and the step `INSERT` have —
+// callers on the hot path ignore it (the close must not block the entry's
+// response), but it gives a test a handle to await before asserting on rows.
+import { getBaseLogger } from '../../core/logging/index.js';
+import { eq, and, getTableColumns } from '../../data/query/index.js';
+import { trace } from '../schema/trace.js';
+import { flushSteps } from '../runtime/flush-steps.js';
+import { copyTraceOnError } from '../retain/copy-on-error.js';
+/** Closes `ctx`'s trace row with `outcome` and flushes its step buffer. No-op when the entry ran untraced. */
+export function closeTrace(instance, ctx, outcome) {
+    if (ctx === null)
+        return Promise.resolve();
+    const closedAt = new Date();
+    return ctx.persisted
+        .then(async () => {
+        const status = ctx.buffer.truncated ? 'truncated' : outcome;
+        const stepFlush = flushSteps(instance, ctx.buffer.drain());
+        const db = instance.pool.getOrCreate(instance.config.database()).drizzle;
+        const table = trace.table();
+        // The composite primary key is `[id, openedDay]` — both are matched so the
+        // UPDATE targets exactly one partition's one row.
+        const cols = getTableColumns(table);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Drizzle's update needs the concrete runtime table type
+        const traceUpdate = db.update(table)
+            .set({ status, closedAt })
+            .where(and(eq(cols.id, ctx.id), eq(cols.openedDay, ctx.openedDay)));
+        await Promise.all([stepFlush, traceUpdate]);
+        // Copy errored / truncated traces to the cold set before their hot
+        // partition retires (Q4). For a truncated trace, `truncationDone` is the
+        // settle handle from `truncateTrace`; awaiting it ensures the cold row
+        // reflects `truncated_at_seq`. For a normal error close the handle is
+        // `null`, and `await null` is a no-op — no branch needed.
+        if (status !== 'closed') {
+            await ctx.buffer.truncationDone;
+            await copyTraceOnError(db, ctx.id);
+        }
+    })
+        .catch((err) => {
+        getBaseLogger().error({ err, traceId: ctx.id }, 'Failed to persist trace close — the trace row is stuck open');
+    });
+}
+//# sourceMappingURL=close-trace.js.map

package/dist/trace/entry/close-trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"close-trace.js","sourceRoot":"","sources":["../../../src/trace/entry/close-trace.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,8EAA8E;AAC9E,8EAA8E;AAC9E,+EAA+E;AAC/E,oDAAoD;AACpD,EAAE;AACF,4EAA4E;AAC5E,+EAA+E;AAC/E,+EAA+E;AAC/E,6EAA6E;AAC7E,oDAAoD;AACpD,EAAE;AACF,8EAA8E;AAC9E,0EAA0E;AAC1E,6EAA6E;AAG7E,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAC3D,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAEpE,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAM7D,8GAA8G;AAC9G,MAAM,UAAU,UAAU,CACxB,QAAkB,EAClB,GAAwB,EACxB,OAAqB;IAErB,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;IAC1C,MAAM,QAAQ,GAAG,IAAI,IAAI,EAAE,CAAA;IAC3B,OAAO,GAAG,CAAC,SAAS;SACjB,IAAI,CAAC,KAAK,IAAI,EAAE;QACf,MAAM,MAAM,GAAqC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,CAAA;QAC7F,MAAM,SAAS,GAAG,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAA;QAC1D,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAA;QACxE,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,CAAA;QAC3B,2EAA2E;QAC3E,kDAAkD;QAClD,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,CAAuC,CAAA;QACzE,wHAAwH;QACxH,MAAM,WAAW,GAAI,EAAU,CAAC,MAAM,CAAC,KAAK,CAAC;aAC1C,GAAG,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;aACzB,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAA;QACrE,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAA;QAC3C,mEAAmE;QACnE,yEAAyE;QACzE,uEAAuE;QACvE,sEAAsE;QACtE,0DAA0D;QAC1D,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;YACxB,MAAM,GAAG,CAAC,MAAM,CAAC,cAAc,CAAA;YAC/B,MAAM,gBAAgB,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,CAAA;QACpC,CAAC;IACH,CAAC,CAAC;SACD,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACtB,aAAa,EAAE,CAAC,KAAK,CACnB,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,EAAE,EACxB,6DAA6D,CAC9D,CAAA;IACH,CAAC,CAAC,CAAA;AACN,CAAC"}

package/dist/trace/entry/finalize-trace.d.ts

@@ -0,0 +1,5 @@
+import type { Manifold } from '../../core/pipework.js';
+import type { TraceContext } from './trace-context.js';
+/** Wraps `result`, closing `ctx`'s trace when it settles. Returns `result` unchanged. */
+export declare function finalizeTrace<T>(instance: Manifold, ctx: TraceContext | null, result: T): T;
+//# sourceMappingURL=finalize-trace.d.ts.map

package/dist/trace/entry/finalize-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finalize-trace.d.ts","sourceRoot":"","sources":["../../../src/trace/entry/finalize-trace.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAGtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD,yFAAyF;AACzF,wBAAgB,aAAa,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,YAAY,GAAG,IAAI,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAgB3F"}

package/dist/trace/entry/finalize-trace.js

@@ -0,0 +1,23 @@
+// Ties a trace's close to the settling of the entry's work: `closed` on a
+// clean return, `error` on a throw. An entry's work may be synchronous or a
+// promise — this handles both and hands the result straight back, so an
+// ingress can wrap its return value inline without restructuring.
+import { closeTrace } from './close-trace.js';
+import { isThenable } from '../runtime/thenable.js';
+/** Wraps `result`, closing `ctx`'s trace when it settles. Returns `result` unchanged. */
+export function finalizeTrace(instance, ctx, result) {
+    if (ctx === null)
+        return result;
+    if (isThenable(result)) {
+        return result.then((value) => {
+            void closeTrace(instance, ctx, 'closed');
+            return value;
+        }, (err) => {
+            void closeTrace(instance, ctx, 'error');
+            throw err;
+        });
+    }
+    void closeTrace(instance, ctx, 'closed');
+    return result;
+}
+//# sourceMappingURL=finalize-trace.js.map

package/dist/trace/entry/finalize-trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"finalize-trace.js","sourceRoot":"","sources":["../../../src/trace/entry/finalize-trace.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,4EAA4E;AAC5E,wEAAwE;AACxE,kEAAkE;AAGlE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAGnD,yFAAyF;AACzF,MAAM,UAAU,aAAa,CAAI,QAAkB,EAAE,GAAwB,EAAE,MAAS;IACtF,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,MAAM,CAAA;IAC/B,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACvB,OAAO,MAAM,CAAC,IAAI,CAChB,CAAC,KAAc,EAAE,EAAE;YACjB,KAAK,UAAU,CAAC,QAAQ,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAA;YACxC,OAAO,KAAK,CAAA;QACd,CAAC,EACD,CAAC,GAAY,EAAE,EAAE;YACf,KAAK,UAAU,CAAC,QAAQ,EAAE,GAAG,EAAE,OAAO,CAAC,CAAA;YACvC,MAAM,GAAG,CAAA;QACX,CAAC,CACG,CAAA;IACR,CAAC;IACD,KAAK,UAAU,CAAC,QAAQ,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAA;IACxC,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/trace/entry/open-trace.d.ts

@@ -0,0 +1,26 @@
+import type { Manifold } from '../../core/pipework.js';
+import type { TraceContext, TraceEntryKind } from './trace-context.js';
+/**
+ * The parent reference openTrace actually consumes. Two shapes satisfy it:
+ * an in-process `TraceContext` (the active trace on the surrounding Flow) and
+ * a synthesized `{ id, rootId }` derived from an ingested W3C `traceparent`
+ * header. Either way, only the two fields are needed to wire the trace tree.
+ */
+export interface ParentTraceRef {
+    readonly id: string;
+    readonly rootId: string;
+}
+export interface OpenTraceParams {
+    readonly instance: Manifold;
+    readonly entryKind: TraceEntryKind;
+    /** The parent trace, or `null` for a root entry. */
+    readonly parent: ParentTraceRef | null;
+    readonly tenant: string | null;
+    /** The entry's auth principal — `userId` is read off it when present. */
+    readonly auth: unknown;
+    readonly requestId: string | null;
+    readonly sessionId: string | null;
+}
+/** Generates a trace id, wires it into the tree, and kicks off the opening `INSERT`. */
+export declare function openTrace(params: OpenTraceParams): TraceContext;
+//# sourceMappingURL=open-trace.d.ts.map

package/dist/trace/entry/open-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-trace.d.ts","sourceRoot":"","sources":["../../../src/trace/entry/open-trace.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAKtD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAItE;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;IAClC,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAA;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAClC;AAED,wFAAwF;AACxF,wBAAgB,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,YAAY,CA6C/D"}

package/dist/trace/entry/open-trace.js

@@ -0,0 +1,75 @@
+// Opens the `trace` row for an entry. The row is written eagerly — a trace
+// exists the moment an entry is reached — but the write itself is fire-and-
+// forget: the id and the tree wiring are computed synchronously, so the entry
+// pays no latency, and the `INSERT` runs in the background. Failure to persist
+// is logged, never thrown: a broken trace table must not break the request.
+//
+// The write goes through `instance.pool` directly, not the request transaction
+// — an errored request rolls back, but its trace must survive to be inspected.
+import { randomUUID } from 'node:crypto';
+import { getBaseLogger } from '../../core/logging/index.js';
+import { trace } from '../schema/trace.js';
+import { toDay } from '../partition/day.js';
+import { StepBuffer } from '../runtime/step-buffer.js';
+const MS_PER_DAY = 86_400_000;
+/** Generates a trace id, wires it into the tree, and kicks off the opening `INSERT`. */
+export function openTrace(params) {
+    const id = randomUUID();
+    const openedAt = new Date();
+    const openedDay = toDay(openedAt);
+    const rootId = params.parent?.rootId ?? id;
+    const expiresAt = new Date(openedAt.getTime() + params.instance.config.trace.hotRetentionDays * MS_PER_DAY);
+    const persisted = insertTraceRow(params.instance, {
+        id,
+        openedDay,
+        rootId,
+        parentId: params.parent?.id ?? null,
+        parentStepId: null,
+        entryKind: params.entryKind,
+        status: 'open',
+        tenantId: params.tenant,
+        requestId: params.requestId,
+        sessionId: params.sessionId,
+        userId: extractUserId(params.auth),
+        openedAt,
+        closedAt: null,
+        expiresAt,
+        truncatedAtSeq: null,
+    });
+    // The step cap is `structuralMax × safetyFactor` (Q7). `structuralMax` is the
+    // longest chain of `step` edges through the flow graph, derived by
+    // `pipework check` from the `@downstream` annotations and pinned in
+    // `config.trace.structuralMax`. Unset → no cap; the truncation mechanism is
+    // live but never fires. The cap firing is a bug signal — DAG analysis was
+    // wrong, or unannotated recursion slipped validation — not a load condition.
+    const traceConfig = params.instance.config.trace;
+    const cap = traceConfig.structuralMax !== undefined
+        ? traceConfig.structuralMax * traceConfig.safetyFactor
+        : Infinity;
+    const buffer = new StepBuffer({
+        traceId: id,
+        traceDay: openedDay,
+        cap,
+        captureInputs: traceConfig.captureInputs,
+    });
+    return { id, rootId, openedDay, persisted, buffer };
+}
+function insertTraceRow(instance, row) {
+    const db = instance.pool.getOrCreate(instance.config.database()).drizzle;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Drizzle's insert needs the concrete runtime table type
+    return db.insert(trace.table()).values(row)
+        .then(() => undefined)
+        .catch((err) => {
+        getBaseLogger().error({ err, traceId: row.id }, 'Failed to persist trace open — the trace row is missing');
+    });
+}
+/** Reads `userId` off the auth principal, following the same convention the logger uses. */
+function extractUserId(auth) {
+    if (auth !== null && typeof auth === 'object' && 'userId' in auth) {
+        const userId = auth.userId;
+        if (typeof userId === 'string')
+            return userId;
+    }
+    return null;
+}
+//# sourceMappingURL=open-trace.js.map

package/dist/trace/entry/open-trace.js.map

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

package/dist/trace/entry/parent-trace.d.ts

@@ -0,0 +1,4 @@
+import type { TraceContext } from './trace-context.js';
+/** The trace on the active Flow, or `null` when there is none — the new entry's parent. */
+export declare function parentTrace(): TraceContext | null;
+//# sourceMappingURL=parent-trace.d.ts.map

package/dist/trace/entry/parent-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parent-trace.d.ts","sourceRoot":"","sources":["../../../src/trace/entry/parent-trace.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD,2FAA2F;AAC3F,wBAAgB,WAAW,IAAI,YAAY,GAAG,IAAI,CAEjD"}

package/dist/trace/entry/parent-trace.js

@@ -0,0 +1,10 @@
+// Traces form a tree. A new entry's parent is the trace already running on the
+// active Flow — a job enqueued and awaited inside a request, a nested test
+// context. With no active Flow (the common case for an inbound HTTP request or
+// a worker-claimed job), the new entry is a root.
+import { getContext } from '../../request/context/store.js';
+/** The trace on the active Flow, or `null` when there is none — the new entry's parent. */
+export function parentTrace() {
+    return getContext()?.trace ?? null;
+}
+//# sourceMappingURL=parent-trace.js.map