@insiderfinance/totalfinance 0.1.0

package/modules/workflows/dist/capabilities.js

@@ -0,0 +1,50 @@
+/**
+ * Capabilities (Stage 7B.2, Decision 9): the runtime refuses an operation whose
+ * `requiredCapabilities` are not all present — before parsing the input — with
+ * `operation.capability_missing`, naming the missing ones. The defaults grant reading, analysis, and
+ * proposing; approval, paper execution, and portfolio writes are granted explicitly by the caller.
+ */
+import { ErrorCode, InputError } from '../../core/dist/index.js';
+/** What a caller holds when it names nothing: read, analyze, propose. */
+export const DEFAULT_CAPABILITIES = Object.freeze([
+    'portfolio:read',
+    'analytics:run',
+    'trade:propose',
+]);
+/** The capabilities this stage names; a runtime may grant others (the registry does not enumerate them). */
+export const KNOWN_CAPABILITIES = Object.freeze([
+    'portfolio:read',
+    'analytics:run',
+    'trade:propose',
+    'trade:approve',
+    'trade:paper',
+    'portfolio:write',
+]);
+const CAPABILITY = /^[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$/;
+export function requireCapabilities(functionName, field, value) {
+    if (!Array.isArray(value)) {
+        throw new InputError(`${functionName}: ${field} must be an array of capability names (e.g. 'trade:paper') when present.`, {
+            code: ErrorCode.InputWrongType,
+            context: { function: functionName, field },
+        });
+    }
+    const seen = new Set();
+    value.forEach((name, index) => {
+        if (typeof name !== 'string' || !CAPABILITY.test(name)) {
+            throw new InputError(`${functionName}: ${field}[${index}] must be a capability name of the form 'scope:action' (e.g. 'trade:paper'). Received ${JSON.stringify(name)}.`, {
+                code: typeof name === 'string' ? ErrorCode.InputWrongShape : ErrorCode.InputWrongType,
+                context: { function: functionName, field: `${field}[${index}]` },
+            });
+        }
+        seen.add(name);
+    });
+    return Object.freeze([...seen].sort());
+}
+/** The required capabilities the caller does not hold, sorted — the runtime's gate. Both lists are validated. */
+export function missingCapabilities(required, capabilities) {
+    const functionName = 'missingCapabilities';
+    const needed = requireCapabilities(functionName, 'required', required);
+    const held = new Set(requireCapabilities(functionName, 'capabilities', capabilities));
+    return needed.filter((name) => !held.has(name));
+}
+//# sourceMappingURL=capabilities.js.map

package/modules/workflows/dist/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,0BAAoB,CAAC;AAE3D,yEAAyE;AACzE,MAAM,CAAC,MAAM,oBAAoB,GAAsB,MAAM,CAAC,MAAM,CAAC;IACnE,gBAAgB;IAChB,eAAe;IACf,eAAe;CAChB,CAAC,CAAC;AAEH,4GAA4G;AAC5G,MAAM,CAAC,MAAM,kBAAkB,GAAsB,MAAM,CAAC,MAAM,CAAC;IACjE,gBAAgB;IAChB,eAAe;IACf,eAAe;IACf,eAAe;IACf,aAAa;IACb,iBAAiB;CAClB,CAAC,CAAC;AAEH,MAAM,UAAU,GAAG,mCAAmC,CAAC;AAEvD,MAAM,UAAU,mBAAmB,CACjC,YAAoB,EACpB,KAAa,EACb,KAAc;IAEd,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,UAAU,CAClB,GAAG,YAAY,KAAK,KAAK,0EAA0E,EACnG;YACE,IAAI,EAAE,SAAS,CAAC,cAAc;YAC9B,OAAO,EAAE,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE;SAC3C,CACF,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QAC5B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACvD,MAAM,IAAI,UAAU,CAClB,GAAG,YAAY,KAAK,KAAK,IAAI,KAAK,yFAAyF,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAClJ;gBACE,IAAI,EAAE,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,cAAc;gBACrF,OAAO,EAAE,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,KAAK,IAAI,KAAK,GAAG,EAAE;aACjE,CACF,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AACzC,CAAC;AAED,iHAAiH;AACjH,MAAM,UAAU,mBAAmB,CACjC,QAA2B,EAC3B,YAA+B;IAE/B,MAAM,YAAY,GAAG,qBAAqB,CAAC;IAC3C,MAAM,MAAM,GAAG,mBAAmB,CAAC,YAAY,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;IACvE,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,mBAAmB,CAAC,YAAY,EAAE,cAAc,EAAE,YAAY,CAAC,CAAC,CAAC;IACtF,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AAClD,CAAC"}

package/modules/workflows/dist/envelope-schema.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The JSON Schema of the one result envelope every transport returns (pre-publish interface
+ * repairs, B2). `runOperation` produces an `OperationResult`; the JSON HTTP route sends it as the
+ * body, the CLI prints it, and the MCP server returns it as `structuredContent` — byte-for-byte the
+ * same document. The schema lives here so the OpenAPI document and every MCP tool's `outputSchema`
+ * describe the envelope from one definition, including the branch a large result takes when it is
+ * spilled to an artifact handle.
+ */
+import type { JSONSchema } from '../../core/dist/schema/index.js';
+/**
+ * A `ResourceHandle` — a stored report, job, portfolio, scenario, market, authorization or
+ * journal — as JSON Schema. The kinds and URI namespaces are read from the one handle table, so
+ * the schema can never list fewer kinds than the stores mint (an MCP client validates every
+ * structured result against it).
+ */
+export declare const RESOURCE_HANDLE_SCHEMA: JSONSchema;
+/**
+ * The `structured` slot of a result that exceeded the caller's inline byte budget: the runtime
+ * stored the full output as a report and answered with its handle and a bounded preview.
+ */
+export declare function spilledResultSchema(handle?: JSONSchema): JSONSchema;
+/** A `QuantWarning` as JSON Schema: the typed code, the message and the severity. */
+export declare const QUANT_WARNING_SCHEMA: JSONSchema;
+export interface OperationResultSchemaInput {
+    /** The operation's own structured-output schema, or an open object when it declares none. */
+    structured?: JSONSchema | undefined;
+    /** How to refer to a resource handle — inline by default, or a `$ref` inside an OpenAPI document. */
+    handle?: JSONSchema | undefined;
+}
+/**
+ * The `OperationResult` envelope as JSON Schema: operation and library identity, the summary, the
+ * structured output (or its spilled handle), assumptions, diagnostics with status, identity, the
+ * artifact handles, usage and trace.
+ */
+export declare function operationResultSchema(input?: OperationResultSchemaInput): JSONSchema;
+//# sourceMappingURL=envelope-schema.d.ts.map

package/modules/workflows/dist/envelope-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope-schema.d.ts","sourceRoot":"","sources":["../src/envelope-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAA2B,CAAC;AAQ5D;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,UAsBpC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,GAAE,UAAmC,GAAG,UAAU,CAiB3F;AAED,qFAAqF;AACrF,eAAO,MAAM,oBAAoB,EAAE,UASlC,CAAC;AAEF,MAAM,WAAW,0BAA0B;IACzC,6FAA6F;IAC7F,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACpC,qGAAqG;IACrG,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,GAAE,0BAA+B,GAAG,UAAU,CA0ExF"}

package/modules/workflows/dist/envelope-schema.js

@@ -0,0 +1,152 @@
+/**
+ * The JSON Schema of the one result envelope every transport returns (pre-publish interface
+ * repairs, B2). `runOperation` produces an `OperationResult`; the JSON HTTP route sends it as the
+ * body, the CLI prints it, and the MCP server returns it as `structuredContent` — byte-for-byte the
+ * same document. The schema lives here so the OpenAPI document and every MCP tool's `outputSchema`
+ * describe the envelope from one definition, including the branch a large result takes when it is
+ * spilled to an artifact handle.
+ */
+import { ensureKnownKeys, requireArgumentObject } from '../../core/dist/index.js';
+import { HANDLE_KINDS } from './stores.js';
+const HANDLE_KIND_NAMES = Object.keys(HANDLE_KINDS);
+const HANDLE_NAMESPACES = HANDLE_KIND_NAMES.map((kind) => HANDLE_KINDS[kind].namespace);
+/**
+ * A `ResourceHandle` — a stored report, job, portfolio, scenario, market, authorization or
+ * journal — as JSON Schema. The kinds and URI namespaces are read from the one handle table, so
+ * the schema can never list fewer kinds than the stores mint (an MCP client validates every
+ * structured result against it).
+ */
+export const RESOURCE_HANDLE_SCHEMA = {
+    type: 'object',
+    properties: {
+        uri: { type: 'string', pattern: `^totalfinance://(${HANDLE_NAMESPACES.join('|')})/` },
+        kind: { type: 'string', enum: HANDLE_KIND_NAMES },
+        schema: { type: 'string' },
+        version: { type: 'string' },
+        contentHash: { type: ['string', 'null'] },
+        createdTimestampMs: { type: 'number' },
+        expiresTimestampMs: { type: ['number', 'null'] },
+        provenance: { type: 'object' },
+    },
+    required: [
+        'uri',
+        'kind',
+        'schema',
+        'version',
+        'contentHash',
+        'createdTimestampMs',
+        'expiresTimestampMs',
+        'provenance',
+    ],
+};
+/**
+ * The `structured` slot of a result that exceeded the caller's inline byte budget: the runtime
+ * stored the full output as a report and answered with its handle and a bounded preview.
+ */
+export function spilledResultSchema(handle = RESOURCE_HANDLE_SCHEMA) {
+    // A schema is an open record (any JSON Schema keyword); the one thing to refuse is a non-object.
+    requireArgumentObject('spilledResultSchema', 'handle', handle);
+    return {
+        type: 'object',
+        description: 'The structured output exceeded the inline byte budget and was stored as a report; read `handle.uri` for the full result.',
+        properties: {
+            spilled: { const: true },
+            handle,
+            preview: {
+                type: 'object',
+                description: 'Top-level keys with scalars inline and containers summarized by size.',
+            },
+        },
+        required: ['spilled', 'handle', 'preview'],
+    };
+}
+/** A `QuantWarning` as JSON Schema: the typed code, the message and the severity. */
+export const QUANT_WARNING_SCHEMA = {
+    type: 'object',
+    properties: {
+        code: { type: 'string' },
+        message: { type: 'string' },
+        severity: { type: 'string', enum: ['info', 'warn', 'error'] },
+        context: { type: 'object' },
+    },
+    required: ['code', 'message', 'severity'],
+};
+/**
+ * The `OperationResult` envelope as JSON Schema: operation and library identity, the summary, the
+ * structured output (or its spilled handle), assumptions, diagnostics with status, identity, the
+ * artifact handles, usage and trace.
+ */
+export function operationResultSchema(input = {}) {
+    requireArgumentObject('operationResultSchema', 'input', input);
+    ensureKnownKeys('operationResultSchema', 'input', input, ['structured', 'handle']);
+    // Present-or-absent: a `null` schema is not "the default schema", it is a malformed request.
+    if (input.handle !== undefined)
+        requireArgumentObject('operationResultSchema', 'input.handle', input.handle);
+    if (input.structured !== undefined)
+        requireArgumentObject('operationResultSchema', 'input.structured', input.structured);
+    const handle = input.handle === undefined ? RESOURCE_HANDLE_SCHEMA : input.handle;
+    const structured = input.structured === undefined ? { type: 'object' } : input.structured;
+    return {
+        type: 'object',
+        description: 'runOperation(...) — identity, the structured output (or its spilled handle), assumptions, diagnostics, usage.',
+        properties: {
+            operation: {
+                type: 'object',
+                properties: { id: { type: 'string' }, version: { type: 'string' } },
+                required: ['id', 'version'],
+            },
+            library: {
+                type: 'object',
+                properties: { version: { type: 'string' } },
+                required: ['version'],
+            },
+            summary: { type: 'string' },
+            // `anyOf`, not `oneOf`: an operation that declares an open structured schema would match
+            // the spilled branch too, and a validating client must still accept the result.
+            structured: { anyOf: [structured, spilledResultSchema(handle)] },
+            assumptions: { type: 'object' },
+            diagnostics: {
+                type: 'object',
+                properties: {
+                    warnings: { type: 'array', items: QUANT_WARNING_SCHEMA },
+                    status: { type: 'string', enum: ['complete', 'partial'] },
+                    incomplete: { type: 'array', items: { type: 'string' } },
+                },
+                required: ['warnings', 'status', 'incomplete'],
+            },
+            identity: {
+                type: 'object',
+                properties: {
+                    inputsHash: { type: 'string' },
+                    artifactIds: { type: 'array', items: { type: 'string' } },
+                    snapshotHash: { type: ['string', 'null'] },
+                },
+                required: ['inputsHash', 'artifactIds', 'snapshotHash'],
+            },
+            artifacts: { type: 'array', items: handle },
+            usage: {
+                type: 'object',
+                properties: { inputBytes: { type: 'integer' }, elapsedMs: { type: ['number', 'null'] } },
+                required: ['inputBytes', 'elapsedMs'],
+            },
+            trace: {
+                type: 'object',
+                properties: { requestId: { type: ['string', 'null'] } },
+                required: ['requestId'],
+            },
+        },
+        required: [
+            'operation',
+            'library',
+            'summary',
+            'structured',
+            'assumptions',
+            'diagnostics',
+            'identity',
+            'artifacts',
+            'usage',
+            'trace',
+        ],
+    };
+}
+//# sourceMappingURL=envelope-schema.js.map

package/modules/workflows/dist/envelope-schema.js.map

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

package/modules/workflows/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `@insiderfinance/totalfinance/workflows` — the protocol-neutral operation registry (Stage 7A,
+ * `docs/specs/local-operations-and-transports.md`). One operation definition drives the SDK-facing
+ * runtime, the CLI, the OpenAPI document, and the MCP tools; no transport owns a second schema,
+ * budget, seed rule, or effect classification. Read-only, provider-free, browser-safe.
+ *
+ * ```ts
+ * import { createOperationRegistry, defaultPacks } from '@insiderfinance/totalfinance/workflows';
+ * const registry = createOperationRegistry({ packs: defaultPacks() });
+ * const result = registry.run('totalfinance.option.price', { type: 'call', spot: 100, strike: 105, timeToExpiryYears: 0.25, riskFreeRate: 0.04, volatility: 0.2 });
+ * ```
+ */
+export { OPERATION_ID, defineOperation, describeOperation, operationAnnotations, requireOperation, } from './operation.js';
+export type { ArtifactStoreReader, OperationAnnotations, OperationAuthorization, OperationContext, OperationCostClass, OperationDescription, OperationError, OperationIdempotency, OperationOutput, OperationPack, OperationResult, OperationSideEffect, OperationSignal, TotalFinanceOperation, ResourceHandle, ResourceHandleKind, } from './operation.js';
+export { OPERATION_BUDGETS, runOperation, toOperationError } from './runtime.js';
+export type { RunOperationInput, RunOperationOptions } from './runtime.js';
+export { createOperationRegistry } from './registry.js';
+export type { OperationRegistry } from './registry.js';
+export { jsonSafe } from './json-safe.js';
+export { RESOURCE_HANDLE_SCHEMA, operationResultSchema, spilledResultSchema, } from './envelope-schema.js';
+export type { OperationResultSchemaInput } from './envelope-schema.js';
+export { HANDLE_KINDS, JOB_STATES, applyJobPatch, createMemoryArtifactStore, createMemoryJobStore, handleUriOf, parseHandleUri, requireArtifactListFilter, requireArtifactPut, requireJobRecord, requireResourceHandle, } from './stores.js';
+export type { ArtifactStore, ArtifactStorePutInput, JobRecord, JobState, JobStore, } from './stores.js';
+export { WORKFLOWS_VERSION } from './version.js';
+export { DEFAULT_CAPABILITIES, KNOWN_CAPABILITIES, missingCapabilities, requireCapabilities, } from './capabilities.js';
+export { EXECUTION_JOURNAL_STORE_CEILING, createMemoryAuthorizationStore, createMemoryExecutionJournalStore, requireAuthorizationPut, requireJournalAppend, requireJournalId, } from './stores-trade.js';
+export type { AuthorizationStore, ExecutionJournalStore, GrantConsumption, } from './stores-trade.js';
+export { tradePack } from './operations-trade.js';
+export { MAX_ROWS, capRows, extendObjectSchema } from './operation-kit.js';
+export { calendarPack, defaultOperations, defaultPacks, optionsPack, performancePack, riskPack, strategyPack, structurePack, technicalAnalysisPack, volatilityPack, } from './operations-compute.js';
+export { analysisOperations, backtestPack, cryptoPack, fixedIncomePack, } from './operations-analysis.js';
+export { artifactPack, journeyOperations, journeyPacks, portfolioPack, valuationPack, researchPack, scenarioPack, } from './operations-journey.js';
+//# sourceMappingURL=index.d.ts.map

package/modules/workflows/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,eAAe,EACf,qBAAqB,EACrB,cAAc,EACd,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACjF,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACxD,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EACL,YAAY,EACZ,UAAU,EACV,aAAa,EACb,yBAAyB,EACzB,oBAAoB,EACpB,WAAW,EACX,cAAc,EACd,yBAAyB,EACzB,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,aAAa,EACb,qBAAqB,EACrB,SAAS,EACT,QAAQ,EACR,QAAQ,GACT,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,+BAA+B,EAC/B,8BAA8B,EAC9B,iCAAiC,EACjC,uBAAuB,EACvB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,eAAe,EACf,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,qBAAqB,EACrB,cAAc,GACf,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,UAAU,EACV,eAAe,GAChB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,aAAa,EACb,YAAY,EACZ,YAAY,GACb,MAAM,yBAAyB,CAAC"}

package/modules/workflows/dist/index.js

@@ -0,0 +1,27 @@
+/**
+ * `@insiderfinance/totalfinance/workflows` — the protocol-neutral operation registry (Stage 7A,
+ * `docs/specs/local-operations-and-transports.md`). One operation definition drives the SDK-facing
+ * runtime, the CLI, the OpenAPI document, and the MCP tools; no transport owns a second schema,
+ * budget, seed rule, or effect classification. Read-only, provider-free, browser-safe.
+ *
+ * ```ts
+ * import { createOperationRegistry, defaultPacks } from '@insiderfinance/totalfinance/workflows';
+ * const registry = createOperationRegistry({ packs: defaultPacks() });
+ * const result = registry.run('totalfinance.option.price', { type: 'call', spot: 100, strike: 105, timeToExpiryYears: 0.25, riskFreeRate: 0.04, volatility: 0.2 });
+ * ```
+ */
+export { OPERATION_ID, defineOperation, describeOperation, operationAnnotations, requireOperation, } from './operation.js';
+export { OPERATION_BUDGETS, runOperation, toOperationError } from './runtime.js';
+export { createOperationRegistry } from './registry.js';
+export { jsonSafe } from './json-safe.js';
+export { RESOURCE_HANDLE_SCHEMA, operationResultSchema, spilledResultSchema, } from './envelope-schema.js';
+export { HANDLE_KINDS, JOB_STATES, applyJobPatch, createMemoryArtifactStore, createMemoryJobStore, handleUriOf, parseHandleUri, requireArtifactListFilter, requireArtifactPut, requireJobRecord, requireResourceHandle, } from './stores.js';
+export { WORKFLOWS_VERSION } from './version.js';
+export { DEFAULT_CAPABILITIES, KNOWN_CAPABILITIES, missingCapabilities, requireCapabilities, } from './capabilities.js';
+export { EXECUTION_JOURNAL_STORE_CEILING, createMemoryAuthorizationStore, createMemoryExecutionJournalStore, requireAuthorizationPut, requireJournalAppend, requireJournalId, } from './stores-trade.js';
+export { tradePack } from './operations-trade.js';
+export { MAX_ROWS, capRows, extendObjectSchema } from './operation-kit.js';
+export { calendarPack, defaultOperations, defaultPacks, optionsPack, performancePack, riskPack, strategyPack, structurePack, technicalAnalysisPack, volatilityPack, } from './operations-compute.js';
+export { analysisOperations, backtestPack, cryptoPack, fixedIncomePack, } from './operations-analysis.js';
+export { artifactPack, journeyOperations, journeyPacks, portfolioPack, valuationPack, researchPack, scenarioPack, } from './operations-journey.js';
+//# sourceMappingURL=index.js.map

package/modules/workflows/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAmBxB,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEjF,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAExD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,YAAY,EACZ,UAAU,EACV,aAAa,EACb,yBAAyB,EACzB,oBAAoB,EACpB,WAAW,EACX,cAAc,EACd,yBAAyB,EACzB,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AAQrB,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,+BAA+B,EAC/B,8BAA8B,EAC9B,iCAAiC,EACjC,uBAAuB,EACvB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,eAAe,EACf,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,qBAAqB,EACrB,cAAc,GACf,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,UAAU,EACV,eAAe,GAChB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,aAAa,EACb,YAAY,EACZ,YAAY,GACb,MAAM,yBAAyB,CAAC"}

package/modules/workflows/dist/json-safe.d.ts

@@ -0,0 +1,7 @@
+/**
+ * JSON-safe normalization of a structured result: every non-finite number (NaN, ±Infinity — a
+ * non-converged inversion, an indicator warmup) becomes `null` at the source, so an in-process
+ * result and its JSON mirror agree and both validate against the advertised output schema.
+ */
+export declare function jsonSafe(value: unknown): unknown;
+//# sourceMappingURL=json-safe.d.ts.map

package/modules/workflows/dist/json-safe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-safe.d.ts","sourceRoot":"","sources":["../src/json-safe.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAahD"}

package/modules/workflows/dist/json-safe.js

@@ -0,0 +1,23 @@
+/**
+ * JSON-safe normalization of a structured result: every non-finite number (NaN, ±Infinity — a
+ * non-converged inversion, an indicator warmup) becomes `null` at the source, so an in-process
+ * result and its JSON mirror agree and both validate against the advertised output schema.
+ */
+export function jsonSafe(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    if (Array.isArray(value))
+        return value.map(jsonSafe);
+    // A typed array (a Float64Array of returns, an Int8Array of option types) serializes as an
+    // object of index keys under JSON.stringify; the wire carries a plain array of its numbers.
+    if (ArrayBuffer.isView(value) && !(value instanceof DataView))
+        return Array.from(value, jsonSafe);
+    if (value !== null && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = jsonSafe(v);
+        return out;
+    }
+    return value;
+}
+//# sourceMappingURL=json-safe.js.map

package/modules/workflows/dist/json-safe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-safe.js","sourceRoot":"","sources":["../src/json-safe.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5E,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACrD,2FAA2F;IAC3F,4FAA4F;IAC5F,IAAI,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,YAAY,QAAQ,CAAC;QAC3D,OAAO,KAAK,CAAC,IAAI,CAAC,KAAqC,EAAE,QAAQ,CAAC,CAAC;IACrE,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QACjE,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/modules/workflows/dist/local/file-lock.d.ts

@@ -0,0 +1,23 @@
+/** Sync new directory entries too: syncing a document alone cannot persist its new ancestors. */
+export declare function ensureDirectory(path: string): void;
+/**
+ * The local job runner creates stores before spawning workers. Observe those workers in their
+ * host: forced termination skips worker finally/exit handlers while the host PID remains alive.
+ * Only a confirmed exit permits clearing that (PID, threadId)'s unique registers. Other hosts
+ * continue to recover whole-process death through kill(pid, 0); no age-based lock stealing.
+ */
+export declare function trackFileLockRoot(directory: string): void;
+/** Durable replacement: sync the complete document, rename, then sync the containing directory. */
+export declare function writeAtomic(path: string, text: string): void;
+/**
+ * A local-filesystem Lamport bakery lock. Every contender owns a unique, immutable pathname;
+ * first announce "choosing", then publish (ticket, token) and wait for all earlier contenders.
+ * Atomic renames make each register read complete. Dead owners' registers can be removed safely:
+ * unlike unlinking/replacing one shared lockfile, reclamation cannot delete a new owner's lock.
+ *
+ * Synchronous, bounded waits; a live owner is NEVER expired by age. Crash-left temp files are not
+ * registers and are ignored. PID reuse fails closed (a bounded timeout), not mutual-exclusion loss.
+ * Requires one host with coherent local filesystem semantics, not a distributed/network lock.
+ */
+export declare function withFileLock<T>(directory: string, execute: () => T): T;
+//# sourceMappingURL=file-lock.d.ts.map

package/modules/workflows/dist/local/file-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock.d.ts","sourceRoot":"","sources":["../../src/local/file-lock.ts"],"names":[],"mappings":"AAuDA,iGAAiG;AACjG,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAQlD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CA+BzD;AAED,mGAAmG;AACnG,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAe5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,CAkEtE"}

package/modules/workflows/dist/local/file-lock.js

@@ -0,0 +1,198 @@
+/// <reference types="node" />
+import { randomUUID } from 'node:crypto';
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { threadId } from 'node:worker_threads';
+import { ErrorCode, InputError } from '../../../core/dist/index.js';
+const pause = new Int32Array(new SharedArrayBuffer(4));
+const active = new Set();
+const roots = new Set();
+const WAIT_MS = 5_000;
+let watchingWorkers = false;
+function missing(error) {
+    return error.code === 'ENOENT';
+}
+function remove(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch (error) {
+        if (!missing(error))
+            throw error;
+    }
+}
+function dead(pid) {
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        // EPERM is not proof of death. Never steal a live or unverifiable owner's lock.
+        return error.code === 'ESRCH';
+    }
+}
+function syncDirectory(path) {
+    const fd = openSync(path, 'r');
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Sync new directory entries too: syncing a document alone cannot persist its new ancestors. */
+export function ensureDirectory(path) {
+    const created = mkdirSync(path, { recursive: true });
+    if (created === undefined)
+        return;
+    const stop = dirname(created);
+    for (let directory = path;; directory = dirname(directory)) {
+        syncDirectory(directory);
+        if (directory === stop)
+            break;
+    }
+}
+/**
+ * The local job runner creates stores before spawning workers. Observe those workers in their
+ * host: forced termination skips worker finally/exit handlers while the host PID remains alive.
+ * Only a confirmed exit permits clearing that (PID, threadId)'s unique registers. Other hosts
+ * continue to recover whole-process death through kill(pid, 0); no age-based lock stealing.
+ */
+export function trackFileLockRoot(directory) {
+    ensureDirectory(directory);
+    roots.add(realpathSync(directory));
+    if (watchingWorkers)
+        return;
+    watchingWorkers = true;
+    process.on('worker', (worker) => {
+        const prefix = `${process.pid}-${worker.threadId}-`;
+        worker.once('exit', () => {
+            const clean = (path) => {
+                try {
+                    for (const entry of readdirSync(path, { withFileTypes: true })) {
+                        const child = join(path, entry.name);
+                        if (entry.isDirectory())
+                            clean(child);
+                        else if (entry.isFile() && entry.name.startsWith(prefix))
+                            remove(child);
+                    }
+                }
+                catch (error) {
+                    if (!missing(error))
+                        throw error;
+                }
+            };
+            for (const root of roots) {
+                try {
+                    clean(root);
+                }
+                catch {
+                    // An inaccessible register remains fail-closed. Cleanup must not crash the host.
+                    process.emitWarning("FileStore: could not clear an exited worker's lock records.", {
+                        code: ErrorCode.OperationInternal,
+                    });
+                }
+            }
+        });
+    });
+}
+/** Durable replacement: sync the complete document, rename, then sync the containing directory. */
+export function writeAtomic(path, text) {
+    const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    let fd;
+    try {
+        fd = openSync(temp, 'wx', 0o600);
+        writeFileSync(fd, text, 'utf8');
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = undefined;
+        renameSync(temp, path);
+        syncDirectory(dirname(path));
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+        remove(temp);
+    }
+}
+/**
+ * A local-filesystem Lamport bakery lock. Every contender owns a unique, immutable pathname;
+ * first announce "choosing", then publish (ticket, token) and wait for all earlier contenders.
+ * Atomic renames make each register read complete. Dead owners' registers can be removed safely:
+ * unlike unlinking/replacing one shared lockfile, reclamation cannot delete a new owner's lock.
+ *
+ * Synchronous, bounded waits; a live owner is NEVER expired by age. Crash-left temp files are not
+ * registers and are ignored. PID reuse fails closed (a bounded timeout), not mutual-exclusion loss.
+ * Requires one host with coherent local filesystem semantics, not a distributed/network lock.
+ */
+export function withFileLock(directory, execute) {
+    ensureDirectory(directory);
+    const root = realpathSync(directory);
+    if (active.has(root)) {
+        throw new InputError('FileStore: nested writes to the same locked resource are not allowed.', {
+            code: ErrorCode.InputWrongShape,
+            context: { function: 'FileStore.lock', field: 'directory' },
+        });
+    }
+    active.add(root);
+    const token = `${process.pid}-${threadId}-${randomUUID()}`;
+    const path = join(root, `${token}.json`);
+    const deadline = performance.now() + WAIT_MS;
+    const wait = () => {
+        if (performance.now() >= deadline) {
+            throw new InputError(`FileStore: timed out after ${WAIT_MS}ms waiting for another writer.`, {
+                code: ErrorCode.OperationDeadlineExceeded,
+                context: { function: 'FileStore.lock', field: 'directory' },
+            });
+        }
+        Atomics.wait(pause, 0, 0, 5);
+    };
+    const read = (name) => {
+        const pid = Number(name.slice(0, name.indexOf('-')));
+        if (dead(pid)) {
+            remove(join(root, name));
+            return undefined;
+        }
+        try {
+            const ticket = JSON.parse(readFileSync(join(root, name), 'utf8'));
+            return ticket === null ? null : BigInt(ticket);
+        }
+        catch (error) {
+            if (missing(error))
+                return undefined;
+            throw error;
+        }
+    };
+    const contenders = () => readdirSync(root).filter((name) => /^\d+-\d+-[a-f0-9-]+\.json$/.test(name));
+    try {
+        writeAtomic(path, 'null');
+        let ticket = 1n;
+        for (const name of contenders()) {
+            const other = read(name);
+            if (other !== undefined && other !== null && other >= ticket)
+                ticket = other + 1n;
+        }
+        writeAtomic(path, JSON.stringify(String(ticket)));
+        for (const name of contenders()) {
+            if (name === `${token}.json`)
+                continue;
+            for (;;) {
+                const other = read(name);
+                if (other === undefined ||
+                    (other !== null && (other > ticket || (other === ticket && name > `${token}.json`))))
+                    break;
+                wait();
+            }
+        }
+        return execute();
+    }
+    finally {
+        try {
+            remove(path);
+        }
+        finally {
+            active.delete(root);
+        }
+    }
+}
+//# sourceMappingURL=file-lock.js.map

package/modules/workflows/dist/local/file-lock.js.map

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