@intentius/chant 0.124.12 → 0.124.14

package/dist/op/decide-backend.js

@@ -0,0 +1,181 @@
+/**
+ * The client for the `POST /v1/systemone` wire format (#2491): TypeSafe's Jev
+ * API, and every server that implements the same request and response.
+ *
+ * ```
+ * POST <url>/v1/systemone          Authorization: Bearer <key>
+ * { "model": "jev-1.13.0", "state": {...}, "questions": { "<name>": { "type": "noul" | "choice" | "score", "instructions": ..., "criteria": ... } } }
+ *
+ * { "model": "jev-1.13.0", "answers": { "<name>": { "type": "noul", "noul": 0.22, "reason"?: ... } | { "type": "choice", "choice": ..., "probabilities": {...}, "confidence": ..., "reason"?: ... } | { "type": "score", ..., "reason"?: ... } } }
+ * ```
+ *
+ * `reason` is optional: the model's own explanation of its answer (#3345).
+ * Core keeps it in the answer record beside a proposal, or as `model_reason`
+ * in the escalation entry of an answer below the threshold.
+ *
+ * {@link backendAsk} turns a set of backends into core's `ModelAsk`, the
+ * model call `askPoint` takes (`../workspace/points.ts`). This file
+ * only speaks the wire format: whether an answer is observed, proposed or
+ * escalated, and what a point does when the backend is unreachable, are
+ * core's (`runChain`), so they are the same for this client, for a response
+ * handed to `points ask --response`, and for any runtime's decider.
+ *
+ * The model id is sent as the point pins it. An alias such as `jev-latest` is
+ * refused where the point is declared, and the response's `model` is compared
+ * with the pin by core, so an alias that moved is never recorded as the pin.
+ *
+ * Anything that stops an answer arriving throws: no key, a network error, a
+ * timeout, a non-2xx status (Jev's are 401, 422, 429 and 529), or a response
+ * without an answer to the question asked. Core reads a throw as the backend
+ * being unreachable and follows the point's `unreachable`.
+ *
+ * It reads the workspace declaration for a brokered key, so it loads code
+ * under `workspace/`: the `decide` activity imports it on first call, never
+ * at module load (#2525 rule 5).
+ */
+import { readDeclaration } from "../workspace/declaration.js";
+import { locateWorkspace } from "../workspace/which-chant.js";
+/** The path every Jev-compatible server serves. */
+export const SYSTEMONE_PATH = "/v1/systemone";
+/** How long a call may take before the backend counts as unreachable, when the backend names no `timeoutMs`. */
+export const DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * The name a point's question is sent under: the point's own name, so a
+ * response reads back the way `points ask --response` reads one, with the
+ * answer under `answers["<point>"]`.
+ */
+export const questionName = (point) => point;
+/** A backend or key that is configured wrongly: the activity refuses before asking anything. */
+export class DecideConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DecideConfigError";
+    }
+}
+/**
+ * The declaration's entry for a brokered key (#2726): the box member that
+ * declares the capability, and the broker it names. Read from the workspace
+ * declaration nearest above `cwd`, the same declaration `workspace status`
+ * reads it from. Throws a {@link DecideConfigError} when no member declares
+ * the capability, when more than one does and the key names none, or when the
+ * capability names no broker.
+ */
+export function brokeredCapability(key, cwd) {
+    let members;
+    try {
+        members = readDeclaration(locateWorkspace(cwd).tree).members;
+    }
+    catch (err) {
+        throw new DecideConfigError(`the key names the brokered capability ${key.capability}, and the workspace declaration can't be read: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const declaring = members.filter((m) => (key.member === undefined || m.name === key.member) && m.box?.capabilities.some((c) => c.name === key.capability));
+    if (declaring.length === 0) {
+        const what = key.member !== undefined ? `member ${key.member}'s box does not declare the capability ${key.capability}` : `no member's box declares the capability ${key.capability}`;
+        throw new DecideConfigError(`${what} (box.capabilities in chant.workspace.json, #2726)`);
+    }
+    if (declaring.length > 1) {
+        throw new DecideConfigError(`the capability ${key.capability} is declared by ${declaring.map((m) => m.name).join(" and ")}: name the member in the key`);
+    }
+    const member = declaring[0];
+    const capability = member.box.capabilities.find((c) => c.name === key.capability);
+    if (capability.broker === null) {
+        throw new DecideConfigError(`member ${member.name}'s capability ${key.capability} names no broker (WSP122), so nothing holds its key`);
+    }
+    return { member: member.name, broker: capability.broker, scope: capability.scope };
+}
+/** Check a key reference without reading any secret: a string is a literal and refused, and a brokered capability must be declared. */
+export function checkKey(key, where, cwd) {
+    if (key === undefined)
+        return;
+    if (typeof key === "string") {
+        throw new DecideConfigError(`${where} is a literal string; a key is { env: "<VARIABLE>" } or a brokered capability, never the key itself (SYS001)`);
+    }
+    if (key !== null && typeof key === "object" && "capability" in key)
+        brokeredCapability(key, cwd);
+}
+/**
+ * The bearer key for one call, or undefined when none is sent: a backend with
+ * no key, or a brokered capability whose broker is the endpoint. Throws when a
+ * variable the key names is unset, which the chain reads as unreachable.
+ */
+export function resolveKey(key, cwd, env = process.env) {
+    if (key === undefined)
+        return undefined;
+    if ("capability" in key) {
+        const brokered = brokeredCapability(key, cwd);
+        if (key.env === undefined)
+            return undefined;
+        const value = env[key.env];
+        if (!value)
+            throw new Error(`the broker ${brokered.broker} has not set ${key.env} for the capability ${key.capability}`);
+        return value;
+    }
+    const value = env[key.env];
+    if (!value)
+        throw new Error(`the environment variable ${key.env} is not set`);
+    return value;
+}
+function short(text) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > 300 ? `${flat.slice(0, 300)}...` : flat;
+}
+/** Post one question to one backend and return the model that answered and its answer. */
+export async function postQuestion(backend, name, request, opts) {
+    const key = resolveKey(backend.key, opts.cwd, opts.env);
+    const question = questionName(request.point);
+    const body = {
+        model: request.model,
+        state: request.state,
+        questions: { [question]: { type: request.question.type, instructions: request.question.instructions, criteria: request.question.criteria } },
+    };
+    const url = `${backend.url.replace(/\/+$/, "")}${SYSTEMONE_PATH}`;
+    const timeout = AbortSignal.timeout(backend.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const signal = opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout;
+    let res;
+    try {
+        res = await (opts.transport ?? fetch)(url, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json", ...(key ? { authorization: `Bearer ${key}` } : {}) },
+            body: JSON.stringify(body),
+            signal,
+        });
+    }
+    catch (err) {
+        const why = timeout.aborted ? `no answer within ${backend.timeoutMs ?? DEFAULT_TIMEOUT_MS} ms` : err instanceof Error ? err.message : String(err);
+        throw new Error(`${name} at ${url}: ${why}`);
+    }
+    const text = await res.text();
+    if (!res.ok)
+        throw new Error(`${name} at ${url} answered ${res.status}${text ? `: ${short(text)}` : ""}`);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`${name} at ${url} answered with something that is not JSON: ${short(text)}`);
+    }
+    const r = parsed;
+    if (r === null || typeof r !== "object")
+        throw new Error(`${name} answered with no JSON object`);
+    if (typeof r.model !== "string" || r.model === "")
+        throw new Error(`${name}'s response names no model`);
+    const answer = r.answers?.[question];
+    if (answer === null || typeof answer !== "object")
+        throw new Error(`${name}'s response has no answer to ${question}`);
+    return { model: r.model, answer, response: r };
+}
+/**
+ * The model call for `askPoint`: each request goes to the backend its decider
+ * names. A name no backend has throws, and so does anything
+ * {@link postQuestion} throws, which the chain reads as unreachable.
+ */
+export function backendAsk(opts) {
+    return async (request) => {
+        const backend = opts.backends[request.backend];
+        if (!backend)
+            throw new Error(`no backend named ${request.backend} is configured (decide.backends)`);
+        const { model, answer, response } = await postQuestion(backend, request.backend, request, opts);
+        opts.onResponse?.(request.backend, response);
+        return { model, answer };
+    };
+}

package/dist/op/decide-config.js

@@ -0,0 +1,68 @@
+/**
+ * The `decide` block in `chant.config.ts`: the backends a decision point's
+ * model decider names, which the `decide` Op activity calls (#2828).
+ *
+ * ```ts
+ * import type { ChantConfig } from "@intentius/chant/config";
+ *
+ * export default {
+ *   decide: {
+ *     backends: {
+ *       systemone: { url: "https://api.typesafe.ai", key: { env: "TYPESAFE_API_KEY" } },
+ *       local: { url: "http://127.0.0.1:8080" },
+ *       studio: { url: "http://127.0.0.1:7071", key: { capability: "inference", member: "box" } },
+ *     },
+ *   },
+ * } satisfies ChantConfig;
+ * ```
+ *
+ * A point's model decider says `"backend": "systemone"`, and that name is the
+ * key here. A backend is an endpoint that speaks the `POST /v1/systemone` wire
+ * format (TypeSafe's, or any server that implements it, #2491) and where its
+ * key comes from.
+ *
+ * The key is never a literal. It is either an environment variable's name, or
+ * a capability the workspace declares as brokered on a box member (#2726).
+ * With a brokered capability the broker holds the credential: it either sets
+ * the variable `env` names for this process, or it is itself the endpoint and
+ * adds the key on the way through, in which case no key is sent from here.
+ * SYS001 refuses a string literal where a key goes.
+ *
+ * This module holds only the schemas, so `../config.ts` can validate the
+ * block without loading the client or anything under `workspace/`.
+ */
+import { z } from "zod";
+/** A key read from an environment variable at call time. */
+export const envKeySchema = z.strictObject({
+    /** The variable's name. */
+    env: z.string().min(1),
+});
+/**
+ * A key reached through a capability a box member declares as brokered
+ * (`box.capabilities` in `chant.workspace.json`, #2726). The capability must be
+ * declared and name a broker, or the call is refused.
+ */
+export const brokeredKeySchema = z.strictObject({
+    /** The capability's name in the box block, such as `inference`. */
+    capability: z.string().min(1),
+    /** The member whose box declares it. Without it, the one member that declares the capability. */
+    member: z.string().min(1).optional(),
+    /**
+     * The environment variable the broker sets with the scoped key. Without it,
+     * the broker is the endpoint and adds the key itself, so none is sent.
+     */
+    env: z.string().min(1).optional(),
+});
+export const keySchema = z.union([envKeySchema, brokeredKeySchema]);
+export const backendSchema = z.strictObject({
+    /** The server's base URL. `/v1/systemone` is appended. */
+    url: z.string().min(1),
+    /** Where the bearer key comes from. Omitted for a server that takes none, such as a local one. */
+    key: keySchema.optional(),
+    /** How long to wait for an answer before the backend counts as unreachable, in milliseconds. Default 30000. */
+    timeoutMs: z.number().int().positive().optional(),
+});
+export const decideConfigSchema = z.strictObject({
+    /** Backend name, as a point's model decider names it, to the backend. */
+    backends: z.record(z.string(), backendSchema).optional(),
+});

package/dist/op/decide-read-inputs.js

@@ -0,0 +1,141 @@
+/**
+ * A point's inputs, read through the read contract.
+ *
+ * A point names each input as a read-contract output, optionally with a
+ * dotted field: `work-item.criteria` is the `criteria` field of a work item as
+ * `records --json` lists it (#2738). The decide activity takes, for each
+ * output, what to read (`read: { "work-item": "W-002" }`), reads it the way
+ * the read contract does, and gives each input its field. Values passed in
+ * `inputs` are taken as given and win over read ones.
+ *
+ * Read by id or name here:
+ *
+ *   record, decision, work-item   a record, by id, from the declared record kinds (`records --json`);
+ *                                 a work item also has its size, `criteria`, `files`, `words` and
+ *                                 `fits_<tier>`, for the slice-tier point (`../workspace/work-size.ts`, #3150)
+ *   member                        a member, by name (`ls --json`)
+ *
+ * The other outputs a point may name (finding, region, commit, node, gate, release,
+ * environment, component) are passed in `inputs`, as the output printed them.
+ * These reads never call a model, and never write. The module loads code
+ * under `workspace/`, so the `decide` activity imports it on first call.
+ */
+import { declaredKindFiles, queryDeclaredRecords } from "../workspace/records-cli.js";
+import { listWorkspace } from "../workspace/ls.js";
+import { inputOutput } from "../workspace/points.js";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { bodyText, loadRecordKind } from "../workspace/records.js";
+import { locateWorkspace } from "../workspace/which-chant.js";
+import { DEFAULT_TIER_LIMITS, measureWorkItem, sizeFields } from "../workspace/work-size.js";
+/** The outputs {@link readInputs} reads by id or name. */
+export const READABLE_OUTPUTS = ["record", "decision", "work-item", "member"];
+/** One output a decide step asked to read that could not be read. */
+export class InputReadError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InputReadError";
+    }
+}
+/** A field of `value` by dotted path, or undefined. */
+export function fieldOf(value, path) {
+    let at = value;
+    for (const part of path.split(".")) {
+        if (at === null || typeof at !== "object" || !Object.prototype.hasOwnProperty.call(at, part))
+            return undefined;
+        at = at[part];
+    }
+    return at;
+}
+async function readRecord(id, cwd, output) {
+    const files = declaredKindFiles(cwd);
+    const set = await queryDeclaredRecords(files, { cwd });
+    const unread = [];
+    for (const [i, doc] of set.kinds.entries()) {
+        if ("error" in doc) {
+            unread.push(`${doc.declared.path}: ${doc.error.code}`);
+            continue;
+        }
+        const found = doc.records.find((r) => r.id === id);
+        if (found) {
+            const record = found;
+            // A work item's size, for the slice-tier point (#3150): criteria, files, words and fits_<tier>.
+            return output === "work-item" ? { ...record, ...(await workItemSizeFields(files[i].file, found.path, found.data, cwd)) } : record;
+        }
+    }
+    throw new InputReadError(`no declared record kind holds a record with id ${id} (read for ${output})${unread.length ? `; not read: ${unread.join(", ")}` : ""}`);
+}
+/** The size fields of a work item of the kind at `kindFile`, measured from its record file. Empty for a kind with no work block. */
+async function workItemSizeFields(kindFile, path, data, cwd) {
+    const loaded = await loadRecordKind(kindFile, cwd);
+    const work = loaded.kind.work;
+    if (!work)
+        return {};
+    const located = locateWorkspace(cwd);
+    let body = "";
+    try {
+        body = bodyText(readFileSync(join(located.top ?? located.rootOnDisk, ...path.split("/")), "utf-8"));
+    }
+    catch {
+        // A record that can't be read again is measured from its front matter alone.
+    }
+    const size = measureWorkItem(data, body, work.acceptance?.field ?? "acceptance");
+    return sizeFields(size, work.tier?.limits ?? DEFAULT_TIER_LIMITS);
+}
+function readMember(name, cwd) {
+    const doc = listWorkspace({ cwd });
+    if ("error" in doc)
+        throw new InputReadError(`the workspace can't be listed: ${doc.error.code}: ${doc.error.message}`);
+    const found = doc.members.find((m) => m.name === name);
+    if (!found)
+        throw new InputReadError(`the workspace has no member named ${name}`);
+    return found;
+}
+/**
+ * The value of one declared input from what was read for its output. A
+ * record's field is looked up in its front matter first, then in the record
+ * as `records --json` lists it (`state`, `valid`, `path`...). An input with no
+ * field is the whole value.
+ */
+function inputValue(input, output, read) {
+    const field = input.length > output.length ? input.slice(output.length + 1) : "";
+    if (field === "")
+        return read;
+    if (output === "member")
+        return fieldOf(read, field);
+    const fromData = fieldOf(read.data, field);
+    return fromData !== undefined ? fromData : fieldOf(read, field);
+}
+/**
+ * Read each output `read` names, and give the point's inputs that name it
+ * their values. Throws an {@link InputReadError} for an output this does not
+ * read, one the point does not name, or an id that is not there.
+ */
+export async function readInputs(declared, read, cwd) {
+    const named = new Set(declared.map(inputOutput));
+    for (const output of Object.keys(read)) {
+        if (!READABLE_OUTPUTS.includes(output)) {
+            throw new InputReadError(`${output} is not read by id here; pass its values in inputs, as the read contract printed them (read takes ${READABLE_OUTPUTS.join(", ")})`);
+        }
+        if (!named.has(output))
+            throw new InputReadError(`the point reads no ${output} input (its inputs are ${declared.join(", ")})`);
+    }
+    const values = new Map();
+    for (const [output, id] of Object.entries(read)) {
+        values.set(output, output === "member" ? readMember(id, cwd) : await readRecord(id, cwd, output));
+    }
+    const inputs = {};
+    const missing = [];
+    for (const input of declared) {
+        const output = inputOutput(input);
+        const value = values.get(output);
+        if (value === undefined)
+            continue;
+        const v = inputValue(input, output, value);
+        if (v === undefined)
+            missing.push(input);
+        else
+            inputs[input] = v;
+    }
+    return { inputs, missing };
+}

package/dist/op/discover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../src/op/discover.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAIxC,OAAO,EAAwB,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE1E,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,QAAQ,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC/B,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AA6GD;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA4CrF;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,kBAAkB,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IACzC,wCAAwC;IACxC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,2GAA2G;IAC3G,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA0C/F"}
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../src/op/discover.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAIxC,OAAO,EAAwB,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAG1E,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,QAAQ,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC/B,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AA6GD;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA6CrF;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,kBAAkB,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IACzC,wCAAwC;IACxC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,2GAA2G;IAC3G,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA2C/F"}

package/dist/op/discover.js

@@ -0,0 +1,213 @@
+import { getRuntime } from "../runtime-adapter.js";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { walkDiscovery, workspaceMemberDirs } from "../discovery/walk.js";
+import { hasDiscoveryMarkerSync } from "../discovery/files.js";
+import { resolveDiscoveryGlobs } from "../config.js";
+import { isStewardDeclaration } from "./steward.js";
+import { ensureTypeScriptLoader } from "../ts-loader.js";
+async function findGitRoot(cwd) {
+    const rt = getRuntime();
+    const result = await rt.spawn(["git", "rev-parse", "--show-toplevel"], { cwd });
+    if (result.exitCode !== 0)
+        throw new Error("Not in a git repository");
+    return result.stdout.trim();
+}
+/**
+ * The root the `*.op.ts` scan starts from (#2058): the nearest chant project
+ * root — the directory holding `chant.config.ts`/`chant.config.json`, walking
+ * up from `cwd` and never past the git root. #1675's convention keeps Op
+ * files OUTSIDE `sourceDir` (`ops/` beside `src/`), which is why discovery
+ * walks up at all — but "up" used to mean the git root unconditionally, so a
+ * chant project nested in a larger checkout (a monorepo, behold's committed
+ * examples) discovered every SIBLING project's Ops as its own. The config
+ * file is the project boundary, the same one entity discovery respects.
+ * With no config anywhere up to the git root, the git root stands —
+ * #1675's original scope, kept for configless layouts.
+ */
+async function findDiscoveryRoot(cwd) {
+    const gitRoot = resolve(await findGitRoot(cwd));
+    let dir = resolve(cwd ?? process.cwd());
+    for (;;) {
+        if (existsSync(join(dir, "chant.config.ts")) || existsSync(join(dir, "chant.config.json")))
+            return dir;
+        if (dir === gitRoot)
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break; // filesystem root — cwd was outside the git root
+        dir = parent;
+    }
+    return gitRoot;
+}
+/**
+ * Every `*.op.ts` file below the Op root, through the one discovery walk
+ * (`../discovery/walk.ts`, #2527). The walk down stops at child projects
+ * whatever the root is, so a configless layout whose Op root is the git root
+ * no longer collects its sibling projects' Ops. The project's
+ * `exclude`/`include` globs and the skip marker apply.
+ */
+async function collectOpFiles(root) {
+    return walkDiscovery({
+        walker: "ops",
+        root,
+        globs: await resolveDiscoveryGlobs(root),
+        excludeDirs: await workspaceMemberDirs(root),
+        accept: (name, full) => name.endsWith(".op.ts") && !name.endsWith(".test.ts") && !name.endsWith(".spec.ts") && !hasDiscoveryMarkerSync(full),
+    });
+}
+/** The `OpConfig` behind an exported value, or `undefined` when the value is not an Op. An Op entity carries its config on `.props` (`./resource.ts`); `name` and `phases` are what every consumer of a discovered Op reads. */
+function opConfigOf(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const config = value.props;
+    if (!config || typeof config.name !== "string" || !Array.isArray(config.phases))
+        return undefined;
+    return config;
+}
+/**
+ * Every Op a module exports, default first (#2171).
+ *
+ * Discovery used to read `mod.default` and nothing else, which made
+ * `export default op` the only shape a runnable Op could take. That is also
+ * the one export shape the fold path refuses (`../discovery/fold-import.ts`
+ * scans for it by name and falls the whole file back to run), so an Op living
+ * under a project's `sourceDir` cost that project its fold coverage, and took
+ * every file importing it down too. Accepting a named export removes the
+ * conflict without moving the fold's rule: the default export still works, so
+ * every Op file written against the documented shape keeps running unchanged.
+ *
+ * Non-Op exports are skipped in silence, not reported. An Op file is ordinary
+ * TypeScript and may export a helper, a config literal or a type alongside its
+ * Op; only a file exporting no Op at all is worth an error.
+ *
+ * A file may carry more than one Op, and each is registered on its own. Ops
+ * are keyed by their declared `config.name`, never by the export name or the
+ * file, so two Ops in one file are no more ambiguous to `chant run` than two
+ * Ops in two files, and the duplicate-name check in {@link discoverOps}
+ * covers both the same way. The same object exported twice (`export default
+ * op` alongside `export { op }`) is one Op, deduplicated by identity, not a
+ * self-collision.
+ *
+ * Export order is the module namespace's own: `default` first by construction
+ * here, then the named exports, which the ECMAScript specification requires a
+ * namespace object to enumerate in sorted order. So the discovered set is
+ * deterministic across runs and platforms.
+ */
+function opsExportedBy(mod) {
+    const found = [];
+    const seen = new Set();
+    const consider = (exportName, value) => {
+        if (seen.has(value))
+            return;
+        const config = opConfigOf(value);
+        if (!config)
+            return;
+        seen.add(value);
+        found.push({ exportName, config });
+    };
+    consider("default", mod.default);
+    for (const exportName of Object.keys(mod)) {
+        if (exportName === "default")
+            continue;
+        consider(exportName, mod[exportName]);
+    }
+    return found;
+}
+/**
+ * Discover all Op definitions from `*.op.ts` files under the nearest chant
+ * project root (the directory holding `chant.config.ts`/`.json`, walking up
+ * from `cwd`), or under the git root when no config exists — see
+ * {@link findDiscoveryRoot} (#2058).
+ *
+ * An Op may be the file's default export or a named one, and a file may hold
+ * several. See {@link opsExportedBy} (#2171).
+ */
+export async function discoverOps(opts) {
+    const errors = [];
+    const ops = new Map();
+    const root = await findDiscoveryRoot(opts?.cwd);
+    const files = await collectOpFiles(root);
+    const nameToFile = new Map();
+    for (const filePath of files) {
+        try {
+            ensureTypeScriptLoader();
+            const mod = (await import(filePath));
+            const exported = opsExportedBy(mod);
+            // A file may hold a steward and no Op (#2731): the steward sits beside
+            // the Ops it runs, and `discoverStewards` reads it from here.
+            if (exported.length === 0 && Object.values(mod).some(isStewardDeclaration))
+                continue;
+            if (exported.length === 0) {
+                errors.push(`${filePath}: exports no Op. Expected \`export default Op({...})\` or a named export such as \`export const deploy = Op({...})\``);
+                continue;
+            }
+            for (const { exportName, config } of exported) {
+                const priorFile = nameToFile.get(config.name);
+                if (priorFile !== undefined) {
+                    errors.push(priorFile === filePath
+                        ? `Duplicate Op name "${config.name}" declared twice in ${filePath}`
+                        : `Duplicate Op name "${config.name}" in ${filePath} and ${priorFile}`);
+                    continue;
+                }
+                nameToFile.set(config.name, filePath);
+                ops.set(config.name, { config, filePath, exportName });
+            }
+        }
+        catch (err) {
+            errors.push(`${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return { ops, errors };
+}
+/**
+ * Every steward declared in the project's `*.op.ts` files (#2731), found the
+ * way {@link discoverOps} finds Ops, keyed by the steward's name.
+ *
+ * Refuses, as errors, the two ways a project could end up with two writers:
+ * two stewards of one name, and one Op listed by two stewards. The steward
+ * declared first (in file walk order) keeps its entry; the other is dropped
+ * and reported in `conflicts`.
+ */
+export async function discoverStewards(opts) {
+    const errors = [];
+    const conflicts = [];
+    const stewards = new Map();
+    const opOwner = new Map();
+    const root = await findDiscoveryRoot(opts?.cwd);
+    const files = await collectOpFiles(root);
+    for (const filePath of files) {
+        let mod;
+        try {
+            ensureTypeScriptLoader();
+            mod = (await import(filePath));
+        }
+        catch (err) {
+            errors.push(`${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+        const seen = new Set();
+        const exportNames = ["default", ...Object.keys(mod).filter((k) => k !== "default")];
+        for (const exportName of exportNames) {
+            const value = mod[exportName];
+            if (!isStewardDeclaration(value) || seen.has(value))
+                continue;
+            seen.add(value);
+            const prior = stewards.get(value.name);
+            if (prior) {
+                conflicts.push(`Duplicate steward "${value.name}" in ${filePath} and ${prior.filePath}`);
+                continue;
+            }
+            const claimed = value.ops.find((op) => opOwner.has(op.name));
+            if (claimed) {
+                conflicts.push(`${filePath}: steward "${value.name}" lists op "${claimed.name}", which steward "${opOwner.get(claimed.name)}" already runs. ` +
+                    `Two stewards running one Op are two writers; list it on one of them.`);
+                continue;
+            }
+            for (const op of value.ops)
+                opOwner.set(op.name, value.name);
+            stewards.set(value.name, { declaration: value, filePath, exportName });
+        }
+    }
+    return { stewards, errors, conflicts };
+}

package/dist/op/duration.js

@@ -0,0 +1,21 @@
+/**
+ * The duration-string parser the Op model uses everywhere a timeout is
+ * authored ("5m", "30s", "1h30m", "100ms"). Its own leaf module so both
+ * `./local-executor.ts` (activity start-to-close timeouts) and `./gate.ts`
+ * (a gate's pending-fact expiry) can reach it without importing each other.
+ * Re-exported from `./local-executor.ts`, which is where it lived and where
+ * every existing caller still imports it from.
+ */
+/** Parse a duration string ("5m", "30s", "1h30m", "100ms") to milliseconds. Throws when nothing in `s` parses as a quantity+unit. */
+export function parseDuration(s) {
+    const units = { ms: 1, s: 1000, m: 60000, h: 3600000, d: 86400000 };
+    let total = 0;
+    let matched = false;
+    for (const m of s.matchAll(/(\d+)(ms|s|m|h|d)/g)) {
+        total += Number(m[1]) * units[m[2]];
+        matched = true;
+    }
+    if (!matched)
+        throw new Error(`unparseable duration: "${s}"`);
+    return total;
+}