@affordance/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @affordance/core — the case framework's engine.
+ *
+ * A **case** is state plus independently-defined guarded **steps**; the
+ * engine computes the currently-available steps (**affordances**) from
+ * guards over state. No declared flow, no program counter;
+ * process changes deploy freely against in-flight cases.
+ *
+ * This barrel *is* the package's interface, and it is curated: the authoring
+ * API an app writes definitions with, the engine it runs them on, the error
+ * taxonomy an adapter translates, and the record types that cross the wire.
+ * The store loaders, the execution lifecycle's internals
+ * and the guard walk live behind the engine — submodules import them from
+ * each other's `index.js`, apps should not need to.
+ */
+export type { Affordance, AffordanceExplanation, BlockedStep, CaseAffordances, CaseSnapshot, Engine, EngineOptions, ExplainOptions, } from './engine/index.js';
+export { createEngine, UnknownCaseTypeError } from './engine/index.js';
+export type { AffordanceErrorCode } from './errors.js';
+export { AffordanceError, isAffordanceError } from './errors.js';
+export type { ClaimedEntryInput, ClaimedJournalEntry, CompletedEntryInput, ExecuteOptions, ExecutionRecord, ExecutionResult, ExecutionStatus, FailureEntryInput, GuardReplay, JournalEntry, JournalEntryInput, JournalEntryType, JournalError, JournalFilter, PatchOp, StateDelta, } from './execution/index.js';
+export { CaseBusyError, ClaimLostError, diffState, foldExecutions, isClaimedEntry, jsonEqual, replayGuard, StepExecutionError, StepNotAvailableError, stepLabel, } from './execution/index.js';
+export type { AnyOfConditionResult, Condition, ConditionContext, ConditionMap, ConditionMapEntry, ConditionOutcome, ConditionResult, ConditionVerdict, Guard, GuardEvaluation, GuardEvaluationContext, GuardSection, Instant, SingleConditionResult, } from './guards/index.js';
+export { anyOf, evaluateGuard, toEpochMs, toIso } from './guards/index.js';
+export type { Correlation, CorrelationRegistration, DeadLetter, DeadLetterFilter, DeadLetterReason, ExternalActor, ExternalEvent, IngestionOptions, IngestionResult, IngestionStatus, } from './ingestion/index.js';
+export { externalActor, routedStep } from './ingestion/index.js';
+export type { MigrationFailure, MigrationOptions, MigrationProgress, MigrationReport, MigrationTransform, } from './migration/index.js';
+export { hasMigrated, migrationStepName } from './migration/index.js';
+export type { ActorMarker, AnyCaseType, BoundStep, CaseTypeDefinition, CaseTypeOptions, CommitWrite, CorrelationRequest, HandlerContext, RetryOptions, RetryPolicy, ScopeDeclaration, ScopedConditionContext, ScopedHandlerContext, ScopedStepHandler, ScopedStepOptions, StepDefinition, StepHandler, StepMetadata, StepOptions, } from './model/index.js';
+export { actor, caseType, DEFAULT_RETRY, SCOPE_FAILURE_CONDITION, ScopeKeyError, StepInputValidationError, stepsOf, UnknownStepError, } from './model/index.js';
+export type { CaseHandle, DatabaseAccess, Dormancy, PoolLike, Queryable, Transaction, } from './store/index.js';
+export { bootstrap, CASE_TABLES, CaseNotFoundError, CaseStateValidationError, FRAMEWORK_SCHEMA, queryableOf, } from './store/index.js';

package/dist/index.js

@@ -0,0 +1,20 @@
+// Copyright © 2026 Mochicode LLC — mochicode.com
+// ── The engine ─────────────────────────────────────────────────────────────
+export { createEngine, UnknownCaseTypeError } from './engine/index.js';
+// ── The error taxonomy: every deliberate refusal, one closed code set ──────
+export { AffordanceError, isAffordanceError } from './errors.js';
+// ── Execution records: what came back, what is journaled ───────────────────
+export { CaseBusyError, ClaimLostError, diffState, foldExecutions, isClaimedEntry, jsonEqual, replayGuard, StepExecutionError, StepNotAvailableError, stepLabel, } from './execution/index.js';
+// ── The authoring API: conditions and guards ───────────────────────────────
+export { anyOf, evaluateGuard, toEpochMs, toIso } from './guards/index.js';
+// ── Ingestion: events in, correlations, dead letters ───────────────────────
+export { externalActor, routedStep } from './ingestion/index.js';
+// ── Migration: the journaled restructure ───────────────────────────────────
+export { hasMigrated, migrationStepName } from './migration/index.js';
+// ── The authoring API: case types and steps ────────────────────────────────
+// `step` itself stays behind the barrel: `caseType` requires a state schema,
+// so `stepsOf` covers every authoring case — one public way to write a step.
+export { actor, caseType, DEFAULT_RETRY, SCOPE_FAILURE_CONDITION, ScopeKeyError, StepInputValidationError, stepsOf, UnknownStepError, } from './model/index.js';
+// ── Persistence: what an app touches directly ──────────────────────────────
+export { bootstrap, CASE_TABLES, CaseNotFoundError, CaseStateValidationError, FRAMEWORK_SCHEMA, queryableOf, } from './store/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iDAAiD;AA4BjD,8EAA8E;AAC9E,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAEtE,8EAA8E;AAC9E,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAmBhE,8EAA8E;AAC9E,OAAO,EACL,aAAa,EACb,cAAc,EACd,SAAS,EACT,cAAc,EACd,cAAc,EACd,SAAS,EACT,WAAW,EACX,kBAAkB,EAClB,qBAAqB,EACrB,SAAS,GACV,MAAM,sBAAsB,CAAA;AAiB7B,8EAA8E;AAC9E,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAa1E,8EAA8E;AAC9E,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAQhE,8EAA8E;AAC9E,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAsBrE,8EAA8E;AAC9E,6EAA6E;AAC7E,6EAA6E;AAC7E,OAAO,EACL,KAAK,EACL,QAAQ,EACR,aAAa,EACb,uBAAuB,EACvB,aAAa,EACb,wBAAwB,EACxB,OAAO,EACP,gBAAgB,GACjB,MAAM,kBAAkB,CAAA;AASzB,8EAA8E;AAC9E,OAAO,EACL,SAAS,EACT,WAAW,EACX,iBAAiB,EACjB,wBAAwB,EACxB,gBAAgB,EAChB,WAAW,GACZ,MAAM,kBAAkB,CAAA","sourcesContent":["// Copyright © 2026 Mochicode LLC — mochicode.com\n\n/**\n * @affordance/core — the case framework's engine.\n *\n * A **case** is state plus independently-defined guarded **steps**; the\n * engine computes the currently-available steps (**affordances**) from\n * guards over state. No declared flow, no program counter;\n * process changes deploy freely against in-flight cases.\n *\n * This barrel *is* the package's interface, and it is curated: the authoring\n * API an app writes definitions with, the engine it runs them on, the error\n * taxonomy an adapter translates, and the record types that cross the wire.\n * The store loaders, the execution lifecycle's internals\n * and the guard walk live behind the engine — submodules import them from\n * each other's `index.js`, apps should not need to.\n */\n\nexport type {\n  Affordance,\n  AffordanceExplanation,\n  BlockedStep,\n  CaseAffordances,\n  CaseSnapshot,\n  Engine,\n  EngineOptions,\n  ExplainOptions,\n} from './engine/index.js'\n// ── The engine ─────────────────────────────────────────────────────────────\nexport { createEngine, UnknownCaseTypeError } from './engine/index.js'\nexport type { AffordanceErrorCode } from './errors.js'\n// ── The error taxonomy: every deliberate refusal, one closed code set ──────\nexport { AffordanceError, isAffordanceError } from './errors.js'\nexport type {\n  ClaimedEntryInput,\n  ClaimedJournalEntry,\n  CompletedEntryInput,\n  ExecuteOptions,\n  ExecutionRecord,\n  ExecutionResult,\n  ExecutionStatus,\n  FailureEntryInput,\n  GuardReplay,\n  JournalEntry,\n  JournalEntryInput,\n  JournalEntryType,\n  JournalError,\n  JournalFilter,\n  PatchOp,\n  StateDelta,\n} from './execution/index.js'\n// ── Execution records: what came back, what is journaled ───────────────────\nexport {\n  CaseBusyError,\n  ClaimLostError,\n  diffState,\n  foldExecutions,\n  isClaimedEntry,\n  jsonEqual,\n  replayGuard,\n  StepExecutionError,\n  StepNotAvailableError,\n  stepLabel,\n} from './execution/index.js'\nexport type {\n  AnyOfConditionResult,\n  Condition,\n  ConditionContext,\n  ConditionMap,\n  ConditionMapEntry,\n  ConditionOutcome,\n  ConditionResult,\n  ConditionVerdict,\n  Guard,\n  GuardEvaluation,\n  GuardEvaluationContext,\n  GuardSection,\n  Instant,\n  SingleConditionResult,\n} from './guards/index.js'\n// ── The authoring API: conditions and guards ───────────────────────────────\nexport { anyOf, evaluateGuard, toEpochMs, toIso } from './guards/index.js'\nexport type {\n  Correlation,\n  CorrelationRegistration,\n  DeadLetter,\n  DeadLetterFilter,\n  DeadLetterReason,\n  ExternalActor,\n  ExternalEvent,\n  IngestionOptions,\n  IngestionResult,\n  IngestionStatus,\n} from './ingestion/index.js'\n// ── Ingestion: events in, correlations, dead letters ───────────────────────\nexport { externalActor, routedStep } from './ingestion/index.js'\nexport type {\n  MigrationFailure,\n  MigrationOptions,\n  MigrationProgress,\n  MigrationReport,\n  MigrationTransform,\n} from './migration/index.js'\n// ── Migration: the journaled restructure ───────────────────────────────────\nexport { hasMigrated, migrationStepName } from './migration/index.js'\nexport type {\n  ActorMarker,\n  AnyCaseType,\n  BoundStep,\n  CaseTypeDefinition,\n  CaseTypeOptions,\n  CommitWrite,\n  CorrelationRequest,\n  HandlerContext,\n  RetryOptions,\n  RetryPolicy,\n  ScopeDeclaration,\n  ScopedConditionContext,\n  ScopedHandlerContext,\n  ScopedStepHandler,\n  ScopedStepOptions,\n  StepDefinition,\n  StepHandler,\n  StepMetadata,\n  StepOptions,\n} from './model/index.js'\n// ── The authoring API: case types and steps ────────────────────────────────\n// `step` itself stays behind the barrel: `caseType` requires a state schema,\n// so `stepsOf` covers every authoring case — one public way to write a step.\nexport {\n  actor,\n  caseType,\n  DEFAULT_RETRY,\n  SCOPE_FAILURE_CONDITION,\n  ScopeKeyError,\n  StepInputValidationError,\n  stepsOf,\n  UnknownStepError,\n} from './model/index.js'\nexport type {\n  CaseHandle,\n  DatabaseAccess,\n  Dormancy,\n  PoolLike,\n  Queryable,\n  Transaction,\n} from './store/index.js'\n// ── Persistence: what an app touches directly ──────────────────────────────\nexport {\n  bootstrap,\n  CASE_TABLES,\n  CaseNotFoundError,\n  CaseStateValidationError,\n  FRAMEWORK_SCHEMA,\n  queryableOf,\n} from './store/index.js'\n"]}

package/dist/ingestion/correlation.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Correlation: the mapping from an external identifier to a case (and a
+ * scope element within it) — CONTEXT.md.
+ *
+ * An e-sign provider knows envelope `env_9f2`; it does not know case
+ * `4b0e…` or that the envelope is buyer #7's agreement. Something has
+ * to hold that mapping, and it has to be the framework, because it is the
+ * framework that has to route the resulting webhook to a step. This is that
+ * something — one of exactly two integration primitives in core (the other
+ * is {@link ingest}). There are no service-specific connectors here, and
+ * there never will be: DocuSign's payload shape is the app's business.
+ *
+ * The registration is written by the handler that *initiates* the external
+ * interaction, in the same commit that records having initiated it —
+ * `ctx.correlate(...)` rides the commit seam, so a case can never be
+ * left having sent an envelope it cannot route the answer for.
+ */
+import type { CorrelationRequest } from '../model/handler.js';
+import type { Queryable } from '../store/index.js';
+/**
+ * A handler's {@link CorrelationRequest} with the case made explicit — what
+ * the registry actually stores. `step` is the step an event on this
+ * identifier should execute when the event does not name one itself:
+ * typically the materializing step, "record what the provider said".
+ */
+export interface CorrelationRegistration extends CorrelationRequest {
+    /** The case the answer belongs to. */
+    readonly caseId: string;
+}
+/** A registered correlation as stored. */
+export interface Correlation {
+    readonly id: string;
+    readonly system: string;
+    readonly externalId: string;
+    readonly caseId: string;
+    readonly scopeKey: string | null;
+    readonly step: string | null;
+    readonly metadata: unknown;
+    readonly createdAt: string;
+}
+/**
+ * Register (or re-register) an external identifier against a case.
+ *
+ * Upserts on `(system, externalId)` — insert, or update the row already
+ * there: a retried handler attempt registering the same envelope again is
+ * not an error, it is the same fact. Pass any
+ * {@link Queryable} — from a handler this is the commit transaction, via
+ * `ctx.correlate` or `ctx.onCommit`.
+ */
+export declare const registerCorrelation: (db: Queryable, registration: CorrelationRegistration) => Promise<Correlation>;
+/** Look up where an external identifier routes; `null` when nothing has claimed it. */
+export declare const lookupCorrelation: (db: Queryable, system: string, externalId: string) => Promise<Correlation | null>;
+/** Every identifier registered against a case — the "what is this case waiting on" view. */
+export declare const correlationsFor: (db: Queryable, caseId: string, scopeKey?: string) => Promise<readonly Correlation[]>;

package/dist/ingestion/correlation.js

@@ -0,0 +1,78 @@
+/**
+ * Correlation: the mapping from an external identifier to a case (and a
+ * scope element within it) — CONTEXT.md.
+ *
+ * An e-sign provider knows envelope `env_9f2`; it does not know case
+ * `4b0e…` or that the envelope is buyer #7's agreement. Something has
+ * to hold that mapping, and it has to be the framework, because it is the
+ * framework that has to route the resulting webhook to a step. This is that
+ * something — one of exactly two integration primitives in core (the other
+ * is {@link ingest}). There are no service-specific connectors here, and
+ * there never will be: DocuSign's payload shape is the app's business.
+ *
+ * The registration is written by the handler that *initiates* the external
+ * interaction, in the same commit that records having initiated it —
+ * `ctx.correlate(...)` rides the commit seam, so a case can never be
+ * left having sent an envelope it cannot route the answer for.
+ */
+import { FRAMEWORK_SCHEMA, mintId } from '../store/index.js';
+const CORRELATIONS = `${FRAMEWORK_SCHEMA}.correlations`;
+const toCorrelation = (row) => ({
+    id: row.id,
+    system: row.system,
+    externalId: row.external_id,
+    caseId: row.case_id,
+    scopeKey: row.scope_key,
+    step: row.step,
+    metadata: row.metadata,
+    createdAt: row.created_at.toISOString(),
+});
+/**
+ * Register (or re-register) an external identifier against a case.
+ *
+ * Upserts on `(system, externalId)` — insert, or update the row already
+ * there: a retried handler attempt registering the same envelope again is
+ * not an error, it is the same fact. Pass any
+ * {@link Queryable} — from a handler this is the commit transaction, via
+ * `ctx.correlate` or `ctx.onCommit`.
+ */
+export const registerCorrelation = async (db, registration) => {
+    const { rows } = await db.query(`insert into ${CORRELATIONS} (id, system, external_id, case_id, scope_key, step, metadata)
+     values ($1, $2, $3, $4, $5, $6, $7::jsonb)
+     on conflict (system, external_id) do update
+       set case_id = excluded.case_id,
+           scope_key = excluded.scope_key,
+           step = excluded.step,
+           metadata = excluded.metadata
+     returning id, system, external_id, case_id, scope_key, step, metadata, created_at`, [
+        mintId('correlation'),
+        registration.system,
+        registration.externalId,
+        registration.caseId,
+        registration.scopeKey ?? null,
+        registration.step ?? null,
+        registration.metadata === undefined
+            ? null
+            : JSON.stringify(registration.metadata),
+    ]);
+    const row = rows[0];
+    if (!row)
+        throw new Error(`insert into ${CORRELATIONS} returned no row`);
+    return toCorrelation(row);
+};
+/** Look up where an external identifier routes; `null` when nothing has claimed it. */
+export const lookupCorrelation = async (db, system, externalId) => {
+    const { rows } = await db.query(`select id, system, external_id, case_id, scope_key, step, metadata, created_at
+     from ${CORRELATIONS} where system = $1 and external_id = $2`, [system, externalId]);
+    const row = rows[0];
+    return row === undefined ? null : toCorrelation(row);
+};
+/** Every identifier registered against a case — the "what is this case waiting on" view. */
+export const correlationsFor = async (db, caseId, scopeKey) => {
+    const { rows } = await db.query(`select id, system, external_id, case_id, scope_key, step, metadata, created_at
+     from ${CORRELATIONS}
+     where case_id = $1 ${scopeKey === undefined ? '' : 'and scope_key = $2'}
+     order by created_at asc`, scopeKey === undefined ? [caseId] : [caseId, scopeKey]);
+    return rows.map(toCorrelation);
+};
+//# sourceMappingURL=correlation.js.map

package/dist/ingestion/correlation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.js","sourceRoot":"","sources":["../../src/ingestion/correlation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAE5D,MAAM,YAAY,GAAG,GAAG,gBAAgB,eAAe,CAAA;AAoCvD,MAAM,aAAa,GAAG,CAAC,GAAmB,EAAe,EAAE,CAAC,CAAC;IAC3D,EAAE,EAAE,GAAG,CAAC,EAAE;IACV,MAAM,EAAE,GAAG,CAAC,MAAM;IAClB,UAAU,EAAE,GAAG,CAAC,WAAW;IAC3B,MAAM,EAAE,GAAG,CAAC,OAAO;IACnB,QAAQ,EAAE,GAAG,CAAC,SAAS;IACvB,IAAI,EAAE,GAAG,CAAC,IAAI;IACd,QAAQ,EAAE,GAAG,CAAC,QAAQ;IACtB,SAAS,EAAE,GAAG,CAAC,UAAU,CAAC,WAAW,EAAE;CACxC,CAAC,CAAA;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,EACtC,EAAa,EACb,YAAqC,EACf,EAAE;IACxB,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC,KAAK,CAC7B,eAAe,YAAY;;;;;;;uFAOwD,EACnF;QACE,MAAM,CAAC,aAAa,CAAC;QACrB,YAAY,CAAC,MAAM;QACnB,YAAY,CAAC,UAAU;QACvB,YAAY,CAAC,MAAM;QACnB,YAAY,CAAC,QAAQ,IAAI,IAAI;QAC7B,YAAY,CAAC,IAAI,IAAI,IAAI;QACzB,YAAY,CAAC,QAAQ,KAAK,SAAS;YACjC,CAAC,CAAC,IAAI;YACN,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,QAAQ,CAAC;KAC1C,CACF,CAAA;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;IACnB,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,eAAe,YAAY,kBAAkB,CAAC,CAAA;IACxE,OAAO,aAAa,CAAC,GAAG,CAAC,CAAA;AAC3B,CAAC,CAAA;AAED,uFAAuF;AACvF,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,EACpC,EAAa,EACb,MAAc,EACd,UAAkB,EACW,EAAE;IAC/B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC,KAAK,CAC7B;YACQ,YAAY,yCAAyC,EAC7D,CAAC,MAAM,EAAE,UAAU,CAAC,CACrB,CAAA;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;IACnB,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAA;AACtD,CAAC,CAAA;AAED,4FAA4F;AAC5F,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,EAClC,EAAa,EACb,MAAc,EACd,QAAiB,EACgB,EAAE;IACnC,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC,KAAK,CAC7B;YACQ,YAAY;0BACE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,oBAAoB;6BAC/C,EACzB,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,CACvD,CAAA;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,CAAA;AAChC,CAAC,CAAA","sourcesContent":["/**\n * Correlation: the mapping from an external identifier to a case (and a\n * scope element within it) — CONTEXT.md.\n *\n * An e-sign provider knows envelope `env_9f2`; it does not know case\n * `4b0e…` or that the envelope is buyer #7's agreement. Something has\n * to hold that mapping, and it has to be the framework, because it is the\n * framework that has to route the resulting webhook to a step. This is that\n * something — one of exactly two integration primitives in core (the other\n * is {@link ingest}). There are no service-specific connectors here, and\n * there never will be: DocuSign's payload shape is the app's business.\n *\n * The registration is written by the handler that *initiates* the external\n * interaction, in the same commit that records having initiated it —\n * `ctx.correlate(...)` rides the commit seam, so a case can never be\n * left having sent an envelope it cannot route the answer for.\n */\n\nimport type { CorrelationRequest } from '../model/handler.js'\nimport type { Queryable } from '../store/index.js'\nimport { FRAMEWORK_SCHEMA, mintId } from '../store/index.js'\n\nconst CORRELATIONS = `${FRAMEWORK_SCHEMA}.correlations`\n\n/**\n * A handler's {@link CorrelationRequest} with the case made explicit — what\n * the registry actually stores. `step` is the step an event on this\n * identifier should execute when the event does not name one itself:\n * typically the materializing step, \"record what the provider said\".\n */\nexport interface CorrelationRegistration extends CorrelationRequest {\n  /** The case the answer belongs to. */\n  readonly caseId: string\n}\n\n/** A registered correlation as stored. */\nexport interface Correlation {\n  readonly id: string\n  readonly system: string\n  readonly externalId: string\n  readonly caseId: string\n  readonly scopeKey: string | null\n  readonly step: string | null\n  readonly metadata: unknown\n  readonly createdAt: string\n}\n\ntype CorrelationRow = {\n  id: string\n  system: string\n  external_id: string\n  case_id: string\n  scope_key: string | null\n  step: string | null\n  metadata: unknown\n  created_at: Date\n}\n\nconst toCorrelation = (row: CorrelationRow): Correlation => ({\n  id: row.id,\n  system: row.system,\n  externalId: row.external_id,\n  caseId: row.case_id,\n  scopeKey: row.scope_key,\n  step: row.step,\n  metadata: row.metadata,\n  createdAt: row.created_at.toISOString(),\n})\n\n/**\n * Register (or re-register) an external identifier against a case.\n *\n * Upserts on `(system, externalId)` — insert, or update the row already\n * there: a retried handler attempt registering the same envelope again is\n * not an error, it is the same fact. Pass any\n * {@link Queryable} — from a handler this is the commit transaction, via\n * `ctx.correlate` or `ctx.onCommit`.\n */\nexport const registerCorrelation = async (\n  db: Queryable,\n  registration: CorrelationRegistration,\n): Promise<Correlation> => {\n  const { rows } = await db.query<CorrelationRow>(\n    `insert into ${CORRELATIONS} (id, system, external_id, case_id, scope_key, step, metadata)\n     values ($1, $2, $3, $4, $5, $6, $7::jsonb)\n     on conflict (system, external_id) do update\n       set case_id = excluded.case_id,\n           scope_key = excluded.scope_key,\n           step = excluded.step,\n           metadata = excluded.metadata\n     returning id, system, external_id, case_id, scope_key, step, metadata, created_at`,\n    [\n      mintId('correlation'),\n      registration.system,\n      registration.externalId,\n      registration.caseId,\n      registration.scopeKey ?? null,\n      registration.step ?? null,\n      registration.metadata === undefined\n        ? null\n        : JSON.stringify(registration.metadata),\n    ],\n  )\n  const row = rows[0]\n  if (!row) throw new Error(`insert into ${CORRELATIONS} returned no row`)\n  return toCorrelation(row)\n}\n\n/** Look up where an external identifier routes; `null` when nothing has claimed it. */\nexport const lookupCorrelation = async (\n  db: Queryable,\n  system: string,\n  externalId: string,\n): Promise<Correlation | null> => {\n  const { rows } = await db.query<CorrelationRow>(\n    `select id, system, external_id, case_id, scope_key, step, metadata, created_at\n     from ${CORRELATIONS} where system = $1 and external_id = $2`,\n    [system, externalId],\n  )\n  const row = rows[0]\n  return row === undefined ? null : toCorrelation(row)\n}\n\n/** Every identifier registered against a case — the \"what is this case waiting on\" view. */\nexport const correlationsFor = async (\n  db: Queryable,\n  caseId: string,\n  scopeKey?: string,\n): Promise<readonly Correlation[]> => {\n  const { rows } = await db.query<CorrelationRow>(\n    `select id, system, external_id, case_id, scope_key, step, metadata, created_at\n     from ${CORRELATIONS}\n     where case_id = $1 ${scopeKey === undefined ? '' : 'and scope_key = $2'}\n     order by created_at asc`,\n    scopeKey === undefined ? [caseId] : [caseId, scopeKey],\n  )\n  return rows.map(toCorrelation)\n}\n"]}

package/dist/ingestion/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The two integration primitives that live in core.
+ *
+ * - **Correlation** — external identifier ↔ (case, scope element). Written
+ *   by the handler that initiates the external interaction.
+ * - **Ingestion** — `ingest(event)`: dedup, correlate, then an ordinary
+ *   Execution with the external system as the actor (materialize-on-event).
+ *
+ * Deliberately absent, permanently: connectors. Nothing in this module knows
+ * what a DocuSign webhook looks like, and nothing in it ever will — the app
+ * owns payload shapes, the framework owns routing and exactly-once.
+ */
+export type { Correlation, CorrelationRegistration } from './correlation.js';
+export { correlationsFor, lookupCorrelation, registerCorrelation, } from './correlation.js';
+export type { DeadLetter, DeadLetterFilter, DeadLetterReason, ExternalActor, ExternalEvent, IngestionEnvironment, IngestionOptions, IngestionResult, IngestionSettings, IngestionStatus, } from './ingest.js';
+export { classifyDeadLetter, externalActor, idempotencyKeyFor, ingest, normalizeIngestion, REOPENS_ON_REDELIVERY, readDeadLetters, routedStep, } from './ingest.js';

package/dist/ingestion/index.js

@@ -0,0 +1,15 @@
+/**
+ * The two integration primitives that live in core.
+ *
+ * - **Correlation** — external identifier ↔ (case, scope element). Written
+ *   by the handler that initiates the external interaction.
+ * - **Ingestion** — `ingest(event)`: dedup, correlate, then an ordinary
+ *   Execution with the external system as the actor (materialize-on-event).
+ *
+ * Deliberately absent, permanently: connectors. Nothing in this module knows
+ * what a DocuSign webhook looks like, and nothing in it ever will — the app
+ * owns payload shapes, the framework owns routing and exactly-once.
+ */
+export { correlationsFor, lookupCorrelation, registerCorrelation, } from './correlation.js';
+export { classifyDeadLetter, externalActor, idempotencyKeyFor, ingest, normalizeIngestion, REOPENS_ON_REDELIVERY, readDeadLetters, routedStep, } from './ingest.js';
+//# sourceMappingURL=index.js.map

package/dist/ingestion/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ingestion/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,kBAAkB,CAAA;AAazB,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,MAAM,EACN,kBAAkB,EAClB,qBAAqB,EACrB,eAAe,EACf,UAAU,GACX,MAAM,aAAa,CAAA","sourcesContent":["/**\n * The two integration primitives that live in core.\n *\n * - **Correlation** — external identifier ↔ (case, scope element). Written\n *   by the handler that initiates the external interaction.\n * - **Ingestion** — `ingest(event)`: dedup, correlate, then an ordinary\n *   Execution with the external system as the actor (materialize-on-event).\n *\n * Deliberately absent, permanently: connectors. Nothing in this module knows\n * what a DocuSign webhook looks like, and nothing in it ever will — the app\n * owns payload shapes, the framework owns routing and exactly-once.\n */\n\nexport type { Correlation, CorrelationRegistration } from './correlation.js'\nexport {\n  correlationsFor,\n  lookupCorrelation,\n  registerCorrelation,\n} from './correlation.js'\nexport type {\n  DeadLetter,\n  DeadLetterFilter,\n  DeadLetterReason,\n  ExternalActor,\n  ExternalEvent,\n  IngestionEnvironment,\n  IngestionOptions,\n  IngestionResult,\n  IngestionSettings,\n  IngestionStatus,\n} from './ingest.js'\nexport {\n  classifyDeadLetter,\n  externalActor,\n  idempotencyKeyFor,\n  ingest,\n  normalizeIngestion,\n  REOPENS_ON_REDELIVERY,\n  readDeadLetters,\n  routedStep,\n} from './ingest.js'\n"]}

package/dist/ingestion/ingest.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Ingestion: external events become Executions.
+ *
+ * A webhook arrives. Three things have to happen, in this order, and each of
+ * them has to be visible afterwards:
+ *
+ * 1. **Dedup.** Providers retry; "at least once" is the delivery guarantee
+ *    every one of them offers. The gate is a unique insert into
+ *    `ingested_events` — not a lookup-then-insert, which races itself — so
+ *    three concurrent deliveries of one event produce exactly one Execution
+ *    and two `duplicate` results.
+ * 2. **Correlate.** The external identifier is resolved to (case, scope,
+ *    step) through the registry the initiating handler wrote.
+ * 3. **Execute.** Through the ordinary claim → run → commit, with the
+ *    external system as the journaled actor. Ingestion has no privileged
+ *    path: the guard still decides, transactionally.
+ *
+ * What is *not* allowed is a quiet drop. An event nothing can route, an event
+ * whose step the guard refuses, an event whose case is busy — each lands in
+ * the same table with a status and a reason, which is the dead-letter
+ * surface. "The webhook definitely arrived, so why is the case still waiting"
+ * is a question this table answers without anyone reading a log file.
+ */
+import type { DeadLetterReason as ContractDeadLetterReason, IngestionStatus as ContractIngestionStatus } from '@affordance/contract';
+import type { ExecutionEnvironment, ExecutionResult, SystemSettled } from '../execution/index.js';
+import type { Queryable } from '../store/index.js';
+import type { Correlation } from './correlation.js';
+/** An event as an external system delivered it. */
+export interface ExternalEvent {
+    /** The system that emitted it, matching the correlation's `system`. */
+    readonly system: string;
+    /** The identifier that routes it — the one the initiating handler registered. */
+    readonly externalId: string;
+    /** What happened, in the provider's own words: `'envelope.completed'`. */
+    readonly type: string;
+    /** The provider's delivery id, when it has one — the strongest dedup key. */
+    readonly eventId?: string;
+    /** The payload, passed to the target step as its input (validated by the step's schema). */
+    readonly payload?: unknown;
+    /** Execute this step instead of the correlation's registered one. */
+    readonly step?: string;
+    /** Override the derived idempotency key — for a provider whose retries are not identical. */
+    readonly idempotencyKey?: string;
+    /** When the external system says it happened (ISO-8601); recorded, never used as `asOf`. */
+    readonly occurredAt?: string;
+}
+/**
+ * How an ingested event ended up: `executed` (the target step ran and
+ * committed), `duplicate` (already seen — this delivery changed nothing, by
+ * design), or `dead-lettered` (nothing could be done with it, and it is
+ * sitting in the dead-letter surface). Wire vocabulary, so the contract
+ * declares it and this is the same closed set.
+ */
+export type IngestionStatus = ContractIngestionStatus;
+/**
+ * Why an event was dead-lettered — the operator's first question, answered.
+ *
+ * Two reasons are ingestion's own (`unrouted`: no correlation claims the
+ * identifier; `no-step`: routed, but neither the event nor the correlation
+ * names a step); every other reason **is** the `AffordanceErrorCode`
+ * the refused Execution already declared at its raise site. Ingestion does
+ * not re-derive the kind of a Refusal — it projects the code the error
+ * carries, so a new refusal class can never misroute here. Wire vocabulary,
+ * declared once by the contract; this is the same closed set.
+ */
+export type DeadLetterReason = ContractDeadLetterReason;
+/**
+ * Whether a provider redelivery of the same event deserves another attempt.
+ *
+ * Total over {@link DeadLetterReason}, so a new code cannot be added without
+ * deciding its reopen policy. `true` marks the outcomes that another delivery
+ * could genuinely cure — the case was busy, the handler crashed. Everything
+ * deterministic (a payload its schema rejects, an address that does not
+ * resolve, a guard that said no) stays dead-lettered: it will be refused the
+ * same way on every retry, so reopening it would only invite endless
+ * redelivery.
+ */
+export declare const REOPENS_ON_REDELIVERY: Record<DeadLetterReason, boolean>;
+/** What {@link ingest} resolves to — always a record, never a throw. */
+export interface IngestionResult {
+    readonly id: string;
+    readonly status: IngestionStatus;
+    readonly system: string;
+    readonly externalId: string;
+    readonly idempotencyKey: string;
+    /** Where it routed, when it routed. */
+    readonly correlation: Correlation | null;
+    /** The Execution it produced, on `executed`. */
+    readonly execution: ExecutionResult | null;
+    /** Why it is in the dead-letter surface, on `dead-lettered`. */
+    readonly reason: DeadLetterReason | null;
+    /** Human-readable detail: the unmet conditions, the failure message. */
+    readonly detail: string | null;
+    readonly receivedAt: string;
+}
+/** A row of the dead-letter surface. */
+export interface DeadLetter {
+    readonly id: string;
+    readonly system: string;
+    readonly externalId: string;
+    readonly type: string;
+    readonly idempotencyKey: string;
+    readonly caseId: string | null;
+    readonly scopeKey: string | null;
+    readonly step: string | null;
+    readonly reason: DeadLetterReason;
+    readonly detail: string | null;
+    readonly event: ExternalEvent;
+    readonly receivedAt: string;
+}
+/** Filters for {@link readDeadLetters}; all optional, all AND-ed. */
+export interface DeadLetterFilter {
+    readonly system?: string;
+    readonly caseId?: string;
+    readonly reason?: DeadLetterReason;
+    readonly limit?: number;
+}
+/** How ingestion presents the external system to guards and the journal. */
+export interface ExternalActor {
+    readonly kind: 'external';
+    readonly system: string;
+    readonly externalId: string;
+    readonly eventType: string;
+}
+/** Engine-level ingestion settings. */
+export interface IngestionOptions {
+    /**
+     * Map an event to the Actor its Execution runs as. Defaults to an
+     * {@link ExternalActor}; an app whose `permits` conditions read its own
+     * actor shape supplies a mapping instead of bending that shape.
+     */
+    readonly actor?: (event: ExternalEvent) => unknown;
+}
+/** The normalized settings the environment carries. */
+export interface IngestionSettings {
+    readonly actor: (event: ExternalEvent) => unknown;
+}
+/**
+ * What {@link ingest} needs from its caller: the execution environment plus
+ * ingestion's own settings. This is the widest environment any subsystem
+ * asks for, so it is also the shape the engine builds once and hands to all
+ * of them — named here so that contract is a type, not a coincidence of an
+ * object literal.
+ */
+export interface IngestionEnvironment extends ExecutionEnvironment {
+    readonly ingestion: IngestionSettings;
+}
+export declare const externalActor: (event: ExternalEvent) => ExternalActor;
+export declare const normalizeIngestion: (options?: IngestionOptions) => IngestionSettings;
+/**
+ * The idempotency key an event dedups on.
+ *
+ * `(system, externalId, type)` is the key's fixed prefix, so the *same*
+ * notification about the *same* envelope produces the same key however many
+ * times it is delivered — and, because an external id resolves to one (case,
+ * scope element), the key is scoped exactly as far as the correlation is. The
+ * tail is the provider's own delivery id where there is one, and a hash of
+ * the payload where there is not: a provider that cannot tell you which
+ * delivery this is gets content-addressed dedup, which is the best anyone
+ * can do.
+ */
+export declare const idempotencyKeyFor: (event: ExternalEvent) => string;
+/**
+ * Which step an ingested event executes: the event's own naming wins,
+ * falling back to what the correlation registered. The precedence is stated
+ * once so any surface that *previews* routing (a dev console's world panel)
+ * asks the same question `ingest` will answer.
+ */
+export declare const routedStep: (event: {
+    readonly step?: string;
+}, correlation: {
+    readonly step: string | null;
+}) => string | null;
+/**
+ * Ingest one external event: dedup, correlate, execute — or dead-letter it
+ * with a reason.
+ *
+ * Never throws for an event's own sake: a webhook endpoint that 500s because
+ * a guard said no teaches the provider to retry something that will never
+ * succeed. Infrastructure failures (the database is gone) do still throw,
+ * because those the caller must not acknowledge.
+ */
+export declare const ingest: (env: IngestionEnvironment, event: ExternalEvent) => Promise<IngestionResult>;
+/**
+ * Project a settled system run onto the reason an operator needs to see —
+ * the one place that asks whether what settled was a Refusal.
+ *
+ * A framework Refusal already names its own kind and explains itself — the
+ * reason is its code, the detail its message (a refused guard's message
+ * carries the unmet conditions, addressed). Anything else is a bug, not a
+ * Refusal; it lands as `execution-failed` so the event is kept, never
+ * silently dropped, with the crash's own words as the detail.
+ */
+export declare const classifyDeadLetter: (ran: SystemSettled) => [DeadLetterReason, string];
+/** Read the dead-letter surface, newest first — the ops view of "arrived, did nothing". */
+export declare const readDeadLetters: (db: Queryable, filter?: DeadLetterFilter) => Promise<readonly DeadLetter[]>;