did-it-land 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Satsawat Natakarnkitkul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# did-it-land
+
+> Your durable worker crashed mid-tool-call. Did the charge actually fire, and how do you
+> reverse it? did-it-land is the per-vendor knowledge that answers both, as data.
+
+```ts
+import { bundled, reconcile, unwind } from "did-it-land";
+
+const charge = bundled().get("stripe.charge");
+
+// After an ambiguous crash: did it land? created_after is a unix-seconds
+// timestamp your workflow records when the order begins.
+const outcome = await reconcile(
+  charge,
+  { order_id: "ORD-1", created_after: orderStartedAt },
+  stripeTransport,
+);
+if (outcome.status === "landed") {
+  // the charge already happened, skip the retry
+}
+
+await unwind(charge, { payment_intent_id: "pi_123" }, stripeTransport);
+```
+
+`stripeTransport` is yours to supply: any object with an async `send(request)`
+returning `{ statusCode, body }` and throwing `TransportError` on timeouts, as shown
+in the quick start's fetch example.
+
+v1 ships four capsules: `stripe.charge`, `s3.delete_object`, `github.merge_pr`, and
+`postgres.insert`. Same corpus as the Python package, with one caveat: the native
+`postgres.insert` capsule needs a handler you register with `registerNative()`, since
+the TS runtime ships no built-in database handlers. Full docs in the repository.
+
+Homepage and docs: https://github.com/netsatsawat/did-it-land
+
+Written by Satsawat Natakarnkitkul. License: MIT.

package/dist/capsule.d.ts

@@ -0,0 +1,66 @@
+export type Method = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
+export type Result = "landed" | "not_landed" | "unknown";
+export type ProbeKind = "http" | "native";
+export type CompKind = "http" | "native" | "none";
+export type ReversibilityClass = "reversible" | "conditionally_reversible" | "irreversible";
+export type Strategy = "client_key" | "natural_key" | "none";
+export interface HttpRequest {
+    method: Method;
+    path: string;
+    query: Record<string, string>;
+    headers: Record<string, string>;
+}
+export interface Rule {
+    result: Result;
+    statusIn?: number[];
+    jsonPath?: string;
+    exists?: boolean;
+    hasEquals: boolean;
+    equals?: unknown;
+    countGte?: number;
+    where?: Record<string, unknown>;
+}
+export interface Confirm {
+    request: HttpRequest;
+    interpret: Rule[];
+}
+export interface Probe {
+    kind: ProbeKind;
+    handler?: string;
+    request?: HttpRequest;
+    interpret: Rule[];
+    confirm?: Confirm;
+}
+export interface Idempotency {
+    strategy: Strategy;
+    header?: string;
+    keys: string[];
+    notes?: string;
+}
+export interface Reversibility {
+    cls: ReversibilityClass;
+    condition?: string;
+}
+export interface Compensation {
+    kind: CompKind;
+    handler?: string;
+    request?: HttpRequest;
+    notes?: string;
+}
+export interface Capsule {
+    id: string;
+    provider: string;
+    operation: string;
+    schemaVersion: string;
+    idempotency: Idempotency;
+    probe: Probe;
+    reversibility: Reversibility;
+    compensation?: Compensation;
+    summary?: string;
+    notes?: string;
+    source?: string | string[];
+}
+export declare const SCHEMA_VERSION = "1";
+export declare class CapsuleError extends Error {
+}
+export declare function capsuleFromDoc(value: unknown, where?: string): Capsule;

package/dist/capsule.js

@@ -0,0 +1,184 @@
+// The capsule data model and a validator that mirrors the Python one. The canonical
+// contract is schema/capsule.schema.json; this rebuilds the same rules with clear errors.
+export const SCHEMA_VERSION = "1";
+export class CapsuleError extends Error {
+}
+const METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"]);
+const STRATEGIES = new Set(["client_key", "natural_key", "none"]);
+const PROBE_KINDS = new Set(["http", "native"]);
+const COMP_KINDS = new Set(["http", "native", "none"]);
+const REV_CLASSES = new Set([
+    "reversible",
+    "conditionally_reversible",
+    "irreversible",
+]);
+const RESULTS = new Set(["landed", "not_landed", "unknown"]);
+function rec(value, where, allowed) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new CapsuleError(`${where}: expected a mapping`);
+    }
+    const doc = value;
+    if (allowed) {
+        // A typo'd key that silently vanished would leave a rule with no
+        // conditions, and a rule with no conditions matches every response.
+        const extras = Object.keys(doc).filter((k) => !allowed.includes(k));
+        if (extras.length) {
+            throw new CapsuleError(`${where}: unknown key(s) ${extras.sort().join(", ")}`);
+        }
+    }
+    return doc;
+}
+function require_(doc, key, where) {
+    if (!(key in doc)) {
+        throw new CapsuleError(`${where}: missing required field '${key}'`);
+    }
+    return doc[key];
+}
+function oneOf(value, allowed, where) {
+    if (typeof value !== "string" || !allowed.has(value)) {
+        const opts = [...allowed].sort().join(", ");
+        throw new CapsuleError(`${where}: '${String(value)}' must be one of ${opts}`);
+    }
+    return value;
+}
+function strMap(value) {
+    const out = {};
+    for (const [k, v] of Object.entries((value ?? {}))) {
+        out[k] = String(v);
+    }
+    return out;
+}
+function keysList(raw, where) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw) || raw.some((x) => typeof x !== "string")) {
+        throw new CapsuleError(`${where}: expected a list of strings`);
+    }
+    return raw;
+}
+function requestFrom(value, where) {
+    const doc = rec(value, where, ["method", "path", "query", "headers"]);
+    const method = oneOf(String(require_(doc, "method", where)).toUpperCase(), METHODS, `${where}.method`);
+    return {
+        method,
+        path: String(require_(doc, "path", where)),
+        query: strMap(doc.query),
+        headers: strMap(doc.headers),
+    };
+}
+function ruleFrom(value, where) {
+    const doc = rec(value, where, ["when", "result"]);
+    const when = rec(doc.when ?? {}, `${where}.when`, [
+        "status_in", "json_path", "exists", "equals", "count_gte", "where",
+    ]);
+    if ("status_in" in when) {
+        const raw = when.status_in;
+        if (!Array.isArray(raw) || raw.some((x) => typeof x !== "number")) {
+            throw new CapsuleError(`${where}.when.status_in: expected a list of numbers`);
+        }
+    }
+    if ("count_gte" in when && typeof when.count_gte !== "number") {
+        throw new CapsuleError(`${where}.when.count_gte: expected a number`);
+    }
+    if ("exists" in when && typeof when.exists !== "boolean") {
+        throw new CapsuleError(`${where}.when.exists: expected a boolean`);
+    }
+    if ("where" in when) {
+        const w = when.where;
+        if (typeof w !== "object" || w === null || Array.isArray(w)) {
+            throw new CapsuleError(`${where}.when.where: expected a mapping`);
+        }
+    }
+    return {
+        result: oneOf(require_(doc, "result", where), RESULTS, `${where}.result`),
+        statusIn: "status_in" in when ? when.status_in : undefined,
+        jsonPath: "json_path" in when ? String(when.json_path) : undefined,
+        exists: "exists" in when ? when.exists : undefined,
+        hasEquals: "equals" in when,
+        equals: "equals" in when ? when.equals : undefined,
+        countGte: "count_gte" in when ? when.count_gte : undefined,
+        where: "where" in when ? when.where : undefined,
+    };
+}
+function probeFrom(value) {
+    const where = "probe";
+    const doc = rec(value, where, ["kind", "handler", "request", "interpret", "confirm"]);
+    const kind = oneOf(require_(doc, "kind", where), PROBE_KINDS, `${where}.kind`);
+    if (kind === "native") {
+        return { kind, handler: String(require_(doc, "handler", where)), interpret: [] };
+    }
+    const request = requestFrom(require_(doc, "request", where), `${where}.request`);
+    const raw = require_(doc, "interpret", where);
+    if (!Array.isArray(raw) || raw.length === 0) {
+        throw new CapsuleError(`${where}.interpret: an http probe needs at least one rule`);
+    }
+    const interpret = raw.map((r, i) => ruleFrom(r, `${where}.interpret[${i}]`));
+    let confirm;
+    if (doc.confirm !== undefined && doc.confirm !== null) {
+        const cdoc = rec(doc.confirm, `${where}.confirm`, ["request", "interpret", "notes"]);
+        const creq = requestFrom(require_(cdoc, "request", `${where}.confirm`), `${where}.confirm.request`);
+        const craw = require_(cdoc, "interpret", `${where}.confirm`);
+        if (!Array.isArray(craw) || craw.length === 0) {
+            throw new CapsuleError(`${where}.confirm.interpret: needs at least one rule`);
+        }
+        confirm = { request: creq, interpret: craw.map((r, i) => ruleFrom(r, `${where}.confirm.interpret[${i}]`)) };
+    }
+    return { kind, request, interpret, confirm };
+}
+function compensationFrom(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const where = "compensation";
+    const doc = rec(value, where, ["kind", "handler", "request", "notes"]);
+    const kind = oneOf(require_(doc, "kind", where), COMP_KINDS, `${where}.kind`);
+    if (kind === "none")
+        return { kind, notes: doc.notes };
+    if (kind === "native") {
+        return {
+            kind,
+            handler: String(require_(doc, "handler", where)),
+            notes: doc.notes,
+        };
+    }
+    return {
+        kind,
+        request: requestFrom(require_(doc, "request", where), `${where}.request`),
+        notes: doc.notes,
+    };
+}
+export function capsuleFromDoc(value, where = "capsule") {
+    const doc = rec(value, where, [
+        "id", "provider", "operation", "schema_version", "summary", "idempotency",
+        "probe", "reversibility", "compensation", "notes", "source",
+    ]);
+    const idemDoc = rec(require_(doc, "idempotency", where), `${where}.idempotency`, ["strategy", "header", "keys", "notes"]);
+    const idempotency = {
+        strategy: oneOf(require_(idemDoc, "strategy", `${where}.idempotency`), STRATEGIES, `${where}.idempotency.strategy`),
+        header: idemDoc.header,
+        keys: keysList(idemDoc.keys, `${where}.idempotency.keys`),
+        notes: idemDoc.notes,
+    };
+    const revDoc = rec(require_(doc, "reversibility", where), `${where}.reversibility`, ["class", "condition"]);
+    const cls = oneOf(require_(revDoc, "class", `${where}.reversibility`), REV_CLASSES, `${where}.reversibility.class`);
+    const condition = revDoc.condition;
+    if (cls === "conditionally_reversible" && !condition) {
+        throw new CapsuleError(`${where}.reversibility: a conditionally_reversible capsule must state its condition`);
+    }
+    const version = String(require_(doc, "schema_version", where));
+    if (version !== SCHEMA_VERSION) {
+        throw new CapsuleError(`${where}: schema_version ${version} is not supported, this runtime reads version ${SCHEMA_VERSION}`);
+    }
+    return {
+        id: String(require_(doc, "id", where)),
+        provider: String(require_(doc, "provider", where)),
+        operation: String(require_(doc, "operation", where)),
+        schemaVersion: String(require_(doc, "schema_version", where)),
+        idempotency,
+        probe: probeFrom(require_(doc, "probe", where)),
+        reversibility: { cls, condition },
+        compensation: compensationFrom(doc.compensation),
+        summary: doc.summary,
+        notes: doc.notes,
+        source: doc.source,
+    };
+}

package/dist/corpus.generated.d.ts

@@ -0,0 +1 @@
+export declare const CORPUS: unknown[];

package/dist/corpus.generated.js

@@ -0,0 +1,407 @@
+// Generated from capsules/ by scripts/build_ts_corpus.py. Do not edit by hand.
+export const CORPUS = [
+    {
+        "id": "github.merge_pr",
+        "provider": "github",
+        "operation": "merge_pr",
+        "schema_version": "1",
+        "summary": "Merge a pull request. Answer whether the merge actually happened, telling a real merge apart from a pull request whose branch was merely deleted.\n",
+        "idempotency": {
+            "strategy": "natural_key",
+            "keys": [
+                "owner",
+                "repo",
+                "pull_number"
+            ],
+            "notes": "A pull request is identified by owner, repo, and number. Merging one that is already merged returns 405, so the natural key is enough to recognize a repeat.\n"
+        },
+        "probe": {
+            "kind": "http",
+            "request": {
+                "method": "GET",
+                "path": "/repos/{owner}/{repo}/pulls/{pull_number}"
+            },
+            "interpret": [
+                {
+                    "when": {
+                        "status_in": [
+                            200
+                        ],
+                        "json_path": "merged",
+                        "equals": true
+                    },
+                    "result": "landed"
+                },
+                {
+                    "when": {
+                        "status_in": [
+                            200
+                        ],
+                        "json_path": "merged",
+                        "equals": false
+                    },
+                    "result": "not_landed"
+                },
+                {
+                    "when": {
+                        "status_in": [
+                            404,
+                            500,
+                            502,
+                            503
+                        ]
+                    },
+                    "result": "unknown"
+                }
+            ]
+        },
+        "reversibility": {
+            "class": "irreversible"
+        },
+        "compensation": {
+            "kind": "none",
+            "notes": "A merge commit is part of history and cannot be truly reversed. The only recourse is a revert, which is a new forward commit rather than an undo, so it is out of scope for a compensation and is left to the caller.\n"
+        },
+        "notes": "The merged field is authoritative. A pull request can look finished because its branch was deleted, yet merged is false, meaning the change never landed. Trusting branch state instead of the merged field is the trap this capsule removes.\n",
+        "source": "https://docs.github.com/en/rest/pulls/pulls#get-a-pull-request"
+    },
+    {
+        "id": "postgres.insert",
+        "provider": "postgres",
+        "operation": "insert",
+        "schema_version": "1",
+        "summary": "Insert a row through a natural key. Answer whether the row committed after a crash, and reverse it with a keyed delete when nothing depends on it yet.\n",
+        "idempotency": {
+            "strategy": "natural_key",
+            "keys": [
+                "table",
+                "key_column",
+                "key_value"
+            ],
+            "notes": "The row carries a business key backed by a unique constraint. Re-running the insert then fails on the constraint rather than duplicating, which is what makes the natural key a safe idempotency handle.\n"
+        },
+        "probe": {
+            "kind": "native",
+            "handler": "postgres_row_exists"
+        },
+        "reversibility": {
+            "class": "conditionally_reversible",
+            "condition": "The row is addressable by its natural key and nothing else references it yet, so a keyed delete returns the table to its prior state. Once dependent rows exist the delete is no longer a clean reversal.\n"
+        },
+        "compensation": {
+            "kind": "native",
+            "handler": "postgres_delete_by_key",
+            "notes": "Delete the row by its natural key inside its own transaction.\n"
+        },
+        "notes": "This capsule is native rather than http because the operation speaks the Postgres wire protocol through a driver, not REST. The probe and compensation are resolved to per-language handlers keyed by id, while the corpus stays the source of the meaning.\n",
+        "source": "https://www.postgresql.org/docs/current/tutorial-transactions.html"
+    },
+    {
+        "id": "s3.delete_object",
+        "provider": "aws_s3",
+        "operation": "delete_object",
+        "schema_version": "1",
+        "summary": "Delete an object from an S3 bucket. Answer whether the object is gone, and restore it only when bucket versioning kept the prior version.\n",
+        "idempotency": {
+            "strategy": "none",
+            "notes": "Deleting an object is naturally idempotent. Repeating the delete against a missing key still returns success, so no idempotency key is needed.\n"
+        },
+        "probe": {
+            "kind": "http",
+            "request": {
+                "method": "HEAD",
+                "path": "/{bucket}/{key}"
+            },
+            "interpret": [
+                {
+                    "when": {
+                        "status_in": [
+                            404
+                        ]
+                    },
+                    "result": "landed"
+                },
+                {
+                    "when": {
+                        "status_in": [
+                            200
+                        ]
+                    },
+                    "result": "not_landed"
+                },
+                {
+                    "when": {
+                        "status_in": [
+                            500,
+                            503
+                        ]
+                    },
+                    "result": "unknown"
+                }
+            ]
+        },
+        "reversibility": {
+            "class": "conditionally_reversible",
+            "condition": "Bucket versioning was enabled at delete time, so the delete wrote a delete marker and retained the previous version. Without versioning the object is gone for good.\n"
+        },
+        "compensation": {
+            "kind": "http",
+            "request": {
+                "method": "DELETE",
+                "path": "/{bucket}/{key}",
+                "query": {
+                    "versionId": "{delete_marker_version_id}"
+                }
+            },
+            "notes": "Restore by deleting the delete marker, which makes the most recent prior version current again. This needs the delete marker version id returned in the original delete response as x-amz-version-id, so capture it at delete time.\n"
+        },
+        "notes": "The probe reports whether the object currently resolves. On a versioned bucket a landed delete still leaves the data recoverable, which is why reversibility is conditional rather than outright.\n",
+        "source": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/DeleteMarker.html"
+    },
+    {
+        "id": "stripe.charge",
+        "provider": "stripe",
+        "operation": "charge",
+        "schema_version": "1",
+        "summary": "Create a payment on Stripe. After an ambiguous crash, answer whether money actually moved, and reverse it with a refund.\n",
+        "idempotency": {
+            "strategy": "client_key",
+            "header": "Idempotency-Key",
+            "notes": "Send a client-generated Idempotency-Key with the create request. A retry with the same key returns the saved result of the first attempt instead of charging again. The key must be derived from state that survives the crash, such as the order id, never minted inside the step, or a re-run bypasses the deduplication. Stripe prunes idempotency keys after 24 hours, so a late recovery cannot rely on key replay and needs the probe below.\n"
+        },
+        "probe": {
+            "kind": "http",
+            "request": {
+                "method": "GET",
+                "path": "/v1/payment_intents/search",
+                "query": {
+                    "query": "metadata[\"order_id\"]:\"{order_id}\""
+                }
+            },
+            "interpret": [
+                {
+                    "when": {
+                        "status_in": [
+                            200
+                        ],
+                        "json_path": "data",
+                        "where": {
+                            "status": "succeeded"
+                        },
+                        "count_gte": 1
+                    },
+                    "result": "landed"
+                },
+                {
+                    "when": {
+                        "status_in": [
+                            200
+                        ],
+                        "json_path": "data",
+                        "where": {
+                            "status": "processing"
+                        },
+                        "count_gte": 1
+                    },
+                    "result": "unknown"
+                },
+                {
+                    "when": {
+                        "status_in": [
+                            200
+                        ],
+                        "json_path": "data",
+                        "where": {
+                            "status": "requires_action"
+                        },
+                        "count_gte": 1
+                    },
+                    "result": "unknown"
+                },
+                {
+                    "when": {
+                        "status_in": [
+                            200
+                        ],
+                        "json_path": "data",
+                        "where": {
+                            "status": "requires_confirmation"
+                        },
+                        "count_gte": 1
+                    },
+                    "result": "unknown"
+                },
+                {
+                    "when": {
+                        "status_in": [
+                            200
+                        ],
+                        "json_path": "data",
+                        "where": {
+                            "status": "requires_capture"
+                        },
+                        "count_gte": 1
+                    },
+                    "result": "unknown"
+                },
+                {
+                    "when": {
+                        "status_in": [
+                            200
+                        ]
+                    },
+                    "result": "not_landed"
+                },
+                {
+                    "when": {
+                        "status_in": [
+                            429,
+                            500,
+                            502,
+                            503
+                        ]
+                    },
+                    "result": "unknown"
+                }
+            ],
+            "confirm": {
+                "request": {
+                    "method": "GET",
+                    "path": "/v1/payment_intents",
+                    "query": {
+                        "limit": "100",
+                        "created[gte]": "{created_after}"
+                    }
+                },
+                "interpret": [
+                    {
+                        "when": {
+                            "status_in": [
+                                200
+                            ],
+                            "json_path": "data",
+                            "where": {
+                                "metadata.order_id": "{order_id}",
+                                "status": "succeeded"
+                            },
+                            "count_gte": 1
+                        },
+                        "result": "landed"
+                    },
+                    {
+                        "when": {
+                            "status_in": [
+                                200
+                            ],
+                            "json_path": "data",
+                            "where": {
+                                "metadata.order_id": "{order_id}",
+                                "status": "processing"
+                            },
+                            "count_gte": 1
+                        },
+                        "result": "unknown"
+                    },
+                    {
+                        "when": {
+                            "status_in": [
+                                200
+                            ],
+                            "json_path": "data",
+                            "where": {
+                                "metadata.order_id": "{order_id}",
+                                "status": "requires_action"
+                            },
+                            "count_gte": 1
+                        },
+                        "result": "unknown"
+                    },
+                    {
+                        "when": {
+                            "status_in": [
+                                200
+                            ],
+                            "json_path": "data",
+                            "where": {
+                                "metadata.order_id": "{order_id}",
+                                "status": "requires_confirmation"
+                            },
+                            "count_gte": 1
+                        },
+                        "result": "unknown"
+                    },
+                    {
+                        "when": {
+                            "status_in": [
+                                200
+                            ],
+                            "json_path": "data",
+                            "where": {
+                                "metadata.order_id": "{order_id}",
+                                "status": "requires_capture"
+                            },
+                            "count_gte": 1
+                        },
+                        "result": "unknown"
+                    },
+                    {
+                        "when": {
+                            "status_in": [
+                                200
+                            ],
+                            "json_path": "has_more",
+                            "equals": true
+                        },
+                        "result": "unknown"
+                    },
+                    {
+                        "when": {
+                            "status_in": [
+                                200
+                            ]
+                        },
+                        "result": "not_landed"
+                    },
+                    {
+                        "when": {
+                            "status_in": [
+                                429,
+                                500,
+                                502,
+                                503
+                            ]
+                        },
+                        "result": "unknown"
+                    }
+                ],
+                "notes": "Search can lag a just-created charge, so an empty search answer is never trusted on its own. This second question walks the List API, which Stripe does not subject to search indexing lag, bounded to intents created since the order began via the created_after context value, and filtered client-side by the caller's order id. Only after that bounded page also comes back empty does the capsule answer not_landed. The bound is what makes has_more meaningful: an unbounded List pages over the whole account history and has_more is simply always true on a mature account, but within the order's own window has_more means more than a hundred intents arrived since this order started, and only then is the absence inconclusive.\n"
+            }
+        },
+        "reversibility": {
+            "class": "reversible"
+        },
+        "compensation": {
+            "kind": "http",
+            "request": {
+                "method": "POST",
+                "path": "/v1/refunds",
+                "query": {
+                    "payment_intent": "{payment_intent_id}"
+                },
+                "headers": {
+                    "Idempotency-Key": "did-it-land-refund-{payment_intent_id}"
+                }
+            },
+            "notes": "Refund the payment intent found by the probe, with its own idempotency key derived from the payment intent id, so a crashed compensation cannot refund twice either. A refund reverses the money movement but Stripe keeps the original processing fees, and on some asynchronous payment methods a refund can fail after being accepted, so treat compensated as accepted, not settled. One more Stripe behavior to know: the key pins the FIRST response for about 24 hours, a failure included. A refund that failed for a fixable reason will replay that same failure on retry under this key, so a deliberate second attempt after fixing the cause needs a fresh key of your own choosing.\n"
+        },
+        "notes": "Context contract: order_id is the caller's own order identifier, attached as metadata when the charge is created, and created_after is a unix timestamp in seconds from just before the order began, which the workflow always owns. The probe asks a sharper question than \"does a payment intent exist\". It filters the search results by status, because an intent stuck at requires_payment_method is a declined card, not a landed charge, and one in processing is money in flight, which is honestly unknown. A matched count above one means a duplicate already exists and one intent needs refunding; the count is surfaced in the outcome's evidence. Two consistency caveats from Stripe's own documentation: search is not for read-after-write flows, since new records can take a short while to become searchable, so an empty result immediately after a crash should be re-checked after a delay (the List API is not subject to that lag and can serve as the fallback); and status filtered in the query text can be served from a cache, which is why the filtering here happens client-side against the returned objects.\n",
+        "source": [
+            "https://docs.stripe.com/api/payment_intents/search",
+            "https://docs.stripe.com/api/payment_intents/list",
+            "https://docs.stripe.com/api/idempotent_requests",
+            "https://docs.stripe.com/metadata",
+            "https://docs.stripe.com/search",
+            "https://docs.stripe.com/payments/paymentintents/lifecycle"
+        ]
+    }
+];

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./capsule.ts";
+export * from "./reconcile.ts";
+export * from "./registry.ts";
+export declare const VERSION = "0.1.0";

package/dist/index.js

@@ -0,0 +1,5 @@
+// did-it-land: know whether a side-effect landed, and how to reverse it.
+export * from "./capsule.js";
+export * from "./reconcile.js";
+export * from "./registry.js";
+export const VERSION = "0.1.0";

package/dist/reconcile.d.ts

@@ -0,0 +1,32 @@
+import type { Capsule, HttpRequest, Result } from "./capsule.ts";
+export interface Response {
+    statusCode: number;
+    body?: unknown;
+}
+export interface Transport {
+    send(req: HttpRequest): Response | Promise<Response>;
+}
+export interface Outcome {
+    status: Result;
+    capsuleId: string;
+    evidence?: Record<string, unknown>;
+}
+export interface CompensationResult {
+    status: string;
+    capsuleId: string;
+    evidence?: Record<string, unknown>;
+}
+export declare class EffectError extends Error {
+}
+/** The service could not be reached or did not answer in time. A transport that
+ * throws this tells reconcile and unwind the question went unanswered, which is an
+ * unknown outcome, not a no. */
+export declare class TransportError extends Error {
+}
+export interface NativeHandler {
+    probe(capsule: Capsule, context: Record<string, unknown>): Outcome | Promise<Outcome>;
+    compensate(capsule: Capsule, context: Record<string, unknown>): CompensationResult | Promise<CompensationResult>;
+}
+export declare function registerNative(id: string, handler: NativeHandler): void;
+export declare function reconcile(capsule: Capsule, context: Record<string, unknown>, transport?: Transport): Promise<Outcome>;
+export declare function unwind(capsule: Capsule, context: Record<string, unknown>, transport?: Transport): Promise<CompensationResult>;

package/dist/reconcile.js

@@ -0,0 +1,171 @@
+// reconcile answers "did it land"; unwind runs the inverse. Both are deterministic given
+// the capsule and the context.
+export class EffectError extends Error {
+}
+/** The service could not be reached or did not answer in time. A transport that
+ * throws this tells reconcile and unwind the question went unanswered, which is an
+ * unknown outcome, not a no. */
+export class TransportError extends Error {
+}
+const HANDLERS = new Map();
+export function registerNative(id, handler) {
+    HANDLERS.set(id, handler);
+}
+function getHandler(id) {
+    const handler = id === undefined ? undefined : HANDLERS.get(id);
+    if (!handler) {
+        const known = [...HANDLERS.keys()].sort().join(", ") || "none";
+        throw new EffectError(`no native handler registered for '${id}' (registered: ${known})`);
+    }
+    return handler;
+}
+function bind(template, context, capsuleId) {
+    return template.replace(/\{([^}]+)\}/g, (_match, name) => {
+        if (!(name in context)) {
+            throw new EffectError(`${capsuleId}: context is missing '${name}', needed by '${template}'`);
+        }
+        return String(context[name]);
+    });
+}
+function bindRequest(req, context, capsuleId) {
+    const query = {};
+    for (const [k, v] of Object.entries(req.query))
+        query[k] = bind(v, context, capsuleId);
+    const headers = {};
+    for (const [k, v] of Object.entries(req.headers))
+        headers[k] = bind(v, context, capsuleId);
+    return { method: req.method, path: bind(req.path, context, capsuleId), query, headers };
+}
+function navigate(body, path) {
+    let cur = body;
+    for (const part of path.split(".")) {
+        if (cur !== null && typeof cur === "object" && !Array.isArray(cur) && part in cur) {
+            cur = cur[part];
+        }
+        else if (Array.isArray(cur) && /^\d+$/.test(part) && Number(part) < cur.length) {
+            cur = cur[Number(part)];
+        }
+        else {
+            return [false, undefined];
+        }
+    }
+    return [true, cur];
+}
+function fieldOf(item, dotted) {
+    let cur = item;
+    for (const part of dotted.split(".")) {
+        if (cur === null || typeof cur !== "object" || !(part in cur))
+            return undefined;
+        cur = cur[part];
+    }
+    return cur;
+}
+function filtered(value, where, context, capsuleId) {
+    if (!where || !Array.isArray(value))
+        return value;
+    const bound = Object.fromEntries(Object.entries(where).map(([k, v]) => [
+        k,
+        typeof v === "string" ? bind(v, context, capsuleId) : v,
+    ]));
+    return value.filter((item) => item !== null &&
+        typeof item === "object" &&
+        Object.entries(bound).every(([k, v]) => fieldOf(item, k) === v));
+}
+function match(rule, resp, context, capsuleId) {
+    const evidence = {};
+    if (rule.statusIn !== undefined && !rule.statusIn.includes(resp.statusCode)) {
+        return [false, evidence];
+    }
+    if (rule.jsonPath !== undefined) {
+        const [found, raw] = navigate(resp.body, rule.jsonPath);
+        const value = filtered(raw, rule.where, context, capsuleId);
+        if (rule.exists !== undefined && found !== rule.exists)
+            return [false, evidence];
+        if (rule.countGte !== undefined) {
+            if (!found || !Array.isArray(value) || value.length < rule.countGte) {
+                return [false, evidence];
+            }
+            evidence.matched = value.length;
+            const ids = value
+                .filter((x) => x !== null && typeof x === "object" && "id" in x)
+                .map((x) => x.id);
+            if (ids.length)
+                evidence.ids = ids;
+        }
+        if (rule.hasEquals && (!found || value !== rule.equals))
+            return [false, evidence];
+    }
+    return [true, evidence];
+}
+export async function reconcile(capsule, context, transport) {
+    const probe = capsule.probe;
+    if (probe.kind === "native") {
+        return getHandler(probe.handler).probe(capsule, context);
+    }
+    if (!transport)
+        throw new EffectError(`${capsule.id}: an http probe needs a transport`);
+    const outcome = await httpProbe(capsule, probe.request, probe.interpret, context, transport);
+    if (outcome.status === "not_landed" && probe.confirm) {
+        const confirmed = await httpProbe(capsule, probe.confirm.request, probe.confirm.interpret, context, transport);
+        return {
+            status: confirmed.status,
+            capsuleId: capsule.id,
+            evidence: { ...confirmed.evidence, confirmed: true },
+        };
+    }
+    return outcome;
+}
+async function httpProbe(capsule, request, interpret, context, transport) {
+    let resp;
+    try {
+        resp = await transport.send(bindRequest(request, context, capsule.id));
+    }
+    catch (err) {
+        if (err instanceof TransportError) {
+            return { status: "unknown", capsuleId: capsule.id, evidence: { transport_error: String(err) } };
+        }
+        throw err;
+    }
+    for (const rule of interpret) {
+        const [ok, evidence] = match(rule, resp, context, capsule.id);
+        if (ok) {
+            evidence.status_code = resp.statusCode;
+            return { status: rule.result, capsuleId: capsule.id, evidence };
+        }
+    }
+    return { status: "unknown", capsuleId: capsule.id, evidence: { status_code: resp.statusCode } };
+}
+export async function unwind(capsule, context, transport) {
+    const comp = capsule.compensation;
+    if (capsule.reversibility.cls === "irreversible") {
+        return { status: "irreversible", capsuleId: capsule.id };
+    }
+    if (!comp || comp.kind === "none") {
+        return { status: "no_compensation", capsuleId: capsule.id };
+    }
+    if (comp.kind === "native") {
+        return getHandler(comp.handler).compensate(capsule, context);
+    }
+    if (!transport)
+        throw new EffectError(`${capsule.id}: an http compensation needs a transport`);
+    let resp;
+    try {
+        resp = await transport.send(bindRequest(comp.request, context, capsule.id));
+    }
+    catch (err) {
+        if (err instanceof TransportError) {
+            return {
+                status: "unknown",
+                capsuleId: capsule.id,
+                evidence: { transport_error: String(err) },
+            };
+        }
+        throw err;
+    }
+    const ok = resp.statusCode >= 200 && resp.statusCode < 300;
+    return {
+        status: ok ? "compensated" : "failed",
+        capsuleId: capsule.id,
+        evidence: { status_code: resp.statusCode },
+    };
+}

package/dist/registry.d.ts

@@ -0,0 +1,10 @@
+import type { Capsule } from "./capsule.ts";
+export declare class Registry {
+    byId: Map<string, Capsule>;
+    constructor(capsules: Capsule[]);
+    get(id: string): Capsule;
+    all(): Capsule[];
+    ids(): string[];
+    get size(): number;
+}
+export declare function bundled(): Registry;

package/dist/registry.js

@@ -0,0 +1,35 @@
+// Load the generated corpus and index it by id.
+import { capsuleFromDoc } from "./capsule.js";
+import { CORPUS } from "./corpus.generated.js";
+import { EffectError } from "./reconcile.js";
+export class Registry {
+    byId;
+    constructor(capsules) {
+        this.byId = new Map();
+        for (const cap of capsules) {
+            if (this.byId.has(cap.id))
+                throw new EffectError(`duplicate capsule id '${cap.id}'`);
+            this.byId.set(cap.id, cap);
+        }
+    }
+    get(id) {
+        const cap = this.byId.get(id);
+        if (!cap) {
+            const known = [...this.byId.keys()].sort().join(", ") || "none";
+            throw new EffectError(`no capsule '${id}' (have: ${known})`);
+        }
+        return cap;
+    }
+    all() {
+        return [...this.byId.values()];
+    }
+    ids() {
+        return [...this.byId.keys()].sort();
+    }
+    get size() {
+        return this.byId.size;
+    }
+}
+export function bundled() {
+    return new Registry(CORPUS.map((doc, i) => capsuleFromDoc(doc, `capsule[${i}]`)));
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "did-it-land",
+  "version": "0.1.0",
+  "description": "Know whether a side-effect landed, and how to reverse it: a corpus of per-vendor effect capsules for durable and saga workflows.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Satsawat Natakarnkitkul",
+  "homepage": "https://github.com/netsatsawat/did-it-land",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/netsatsawat/did-it-land.git",
+    "directory": "typescript"
+  },
+  "keywords": [
+    "durable-execution",
+    "saga",
+    "idempotency",
+    "reconciliation",
+    "agents"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  }
+}