@sponson/core 0.4.0 → 0.6.0

package/dist/resolve.js

@@ -35,12 +35,14 @@ export function markerKind(v) {
 }
 /**
  * Replace `{from}` and `{secret}` leaves.
- * `secretValues` is only passed by apply; plan never resolves secrets.
+ * `secretValues` is only passed by apply; plan never resolves secrets. `keepSpent` decides, per reference to a spent
+ * `once` output, whether it may stand as `{ keep: true }` (by default it may); the engine asks the ledger.
  */
-export function resolveParams(params, outputs, secretValues) {
+export function resolveParams(params, outputs, secretValues, keepSpent = () => true) {
     const inputs = {};
     const pending = [];
     const secrets = [];
+    const spent = [];
     /** An output reference: its value when the line has produced it, else a pending marker. */
     const fromRef = (ref, key) => {
         const [line, ...rest] = ref.split(".");
@@ -51,6 +53,13 @@ export function resolveParams(params, outputs, secretValues) {
             inputs[key] = { state: "resolved", value: sensitive ? null : lo.values[output], ref, sensitive, dependsOn: line };
             return lo.values[output];
         }
+        if (lo?.spent && lo.specs[output]?.once) {
+            // Shown once, in the run that created it: whoever received it then keeps it.
+            const kept = keepSpent(ref, line, output);
+            inputs[key] = { state: kept ? "kept" : "pending", value: null, ref, sensitive, dependsOn: line };
+            spent.push({ path: key, ref, line, kept });
+            return kept ? KEEP_MARKER : pendingMarker(ref);
+        }
         inputs[key] = { state: "pending", value: null, ref, dependsOn: line, sensitive };
         pending.push({ path: key, ref, line });
         return pendingMarker(ref);
@@ -82,7 +91,7 @@ export function resolveParams(params, outputs, secretValues) {
         return value;
     };
     const resolved = rebuild(params, []);
-    return { params: resolved, inputs, pending, secrets };
+    return { params: resolved, inputs, pending, secrets, spent };
 }
 /** All `{secret}` references in a params object. */
 export function secretRefs(params) {

package/dist/resolve.js.map

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

package/dist/testing/fake.d.ts

@@ -2,8 +2,13 @@ import type { ResourceAdapter, SecretSource } from "../types.js";
 /**
  * An in-memory provider for engine tests and property tests.
  *
- * One op, `item`, with params `{ name, value }`:
- *   outputs: id (immediate), secret (immediate, sensitive), url (external: "deploy")
+ * `item`, with params `{ name, value }`:
+ *   outputs: id (immediate), secret (immediate, sensitive), url (external: "deploy"),
+ *            token (sensitive, once: only in the apply that creates the item)
+ *   A `{ keep: true }` value is unchanged when the item exists and PARAM_INVALID when it does not.
+ * `member`, with params `{ list, value }`: one entry of a list stored on a shared parent object, written by
+ *   read-modify-write with a pause in between (`listLatencyMs`), like an Auth0 application's callback URLs.
+ *   `lockOn` names the list (ADR 0019) unless `lockLists` is false, which reproduces the lost update.
  * Chaos knobs let a test fail the n-th write, make the deploy never happen, etc.
  */
 export interface FakeItem {
@@ -15,6 +20,12 @@ export interface FakeItem {
 type FailKind = "apply" | "create" | "lost" | "destroy" | "read";
 export declare class FakeCloud {
     items: Map<string, FakeItem>;
+    /** Lists on shared parent objects, by list name. */
+    lists: Map<string, string[]>;
+    /** Pause between reading a list and writing it back: the window in which a concurrent writer loses an update. */
+    listLatencyMs: number;
+    /** Whether `member` declares its parent object (`lockOn`). */
+    lockLists: boolean;
     writes: Array<{
         op: "create" | "update" | "delete";
         name: string;
@@ -35,6 +46,8 @@ export declare class FakeCloud {
     reset(): void;
     private maybeFail;
     adapter(name?: string): ResourceAdapter;
+    /** One value in a list held by a shared parent object, written by read-modify-write of the whole list. */
+    private memberOp;
 }
 /** Secrets from a map; fingerprint changes with the value. */
 export declare function fakeSecretSource(values: Record<string, string>, scheme?: string): SecretSource;

package/dist/testing/fake.js

@@ -1,7 +1,15 @@
+import { SponsonError } from "../errors.js";
+import { setTimeout as sleep } from "node:timers/promises";
 import { sha256 } from "../hash.js";
 import { isPendingMarker, markerKind, pendingRef } from "../resolve.js";
 export class FakeCloud {
     items = new Map();
+    /** Lists on shared parent objects, by list name. */
+    lists = new Map();
+    /** Pause between reading a list and writing it back: the window in which a concurrent writer loses an update. */
+    listLatencyMs = 0;
+    /** Whether `member` declares its parent object (`lockOn`). */
+    lockLists = true;
     writes = [];
     reads = 0;
     external = "ok";
@@ -30,6 +38,7 @@ export class FakeCloud {
     }
     reset() {
         this.items.clear();
+        this.lists.clear();
         this.writes = [];
         this.reads = 0;
         this.external = "ok";
@@ -55,9 +64,11 @@ export class FakeCloud {
                         id: { available: "immediate" },
                         secret: { available: "immediate", sensitive: true },
                         url: { available: "external", event: "deploy" },
+                        token: { available: "immediate", sensitive: true, once: true },
                     },
                     defaults: (p, ctx) => ({ ...p, name: p.name ?? `item-${ctx.scope}` }),
-                    writesEnvironment: (p) => (typeof p.target === "string" ? p.target : null),
+                    // From the line (`target`), or from the provider block (`providers.fake.production: true`).
+                    writesEnvironment: (p, _ctx, provider) => (typeof p.target === "string" ? p.target : provider?.production === true ? "production" : null),
                     async read(_actx, p) {
                         cloud.reads++;
                         cloud.maybeFail("read", String(p.name));
@@ -71,6 +82,11 @@ export class FakeCloud {
                         const want = p.value;
                         const current = live?.resources.find((r) => r.key === key(n));
                         const marker = markerKind(want);
+                        if (marker === "keep") {
+                            if (current)
+                                return [{ key: key(n), label: n, kind: "unchanged" }];
+                            throw new SponsonError("PARAM_INVALID", `${n} is declared \`{ keep: true }\` but does not exist`, { key: key(n) });
+                        }
                         const after = marker === "pending" || marker === "secret" ? { state: marker, ref: pendingRef(want) } : { state: "literal", value: String(want) };
                         if (!current)
                             return [{ key: key(n), label: n, kind: "create", after }];
@@ -85,7 +101,7 @@ export class FakeCloud {
                         cloud.maybeFail("apply", n);
                         const existing = cloud.items.get(n);
                         if (existing) {
-                            if (existing.value !== String(p.value)) {
+                            if (markerKind(p.value) !== "keep" && existing.value !== String(p.value)) {
                                 existing.value = String(p.value);
                                 cloud.writes.push({ op: "update", name: n });
                             }
@@ -98,7 +114,7 @@ export class FakeCloud {
                         cloud.writes.push({ op: "create", name: n });
                         cloud.maybeFail("lost", n); // the write happened; the response did not arrive
                         void live;
-                        return { resources: [record(it)], outputs: outputsOf(it), created: [key(n)] };
+                        return { resources: [record(it)], outputs: { ...outputsOf(it), token: `t-${it.id}-${it.name}` }, created: [key(n)] };
                     },
                     async destroy(_actx, resources) {
                         for (const r of resources) {
@@ -119,6 +135,56 @@ export class FakeCloud {
                         return [...cloud.items.values()].map(record);
                     },
                 },
+                member: this.memberOp(),
+            },
+        };
+    }
+    /** One value in a list held by a shared parent object, written by read-modify-write of the whole list. */
+    memberOp() {
+        const cloud = this;
+        const key = (list, v) => `member:${list}:${v}`;
+        const record = (list, v) => ({ key: key(list, v), id: `${list}/${v}`, hash: sha256(v), label: `${v} in ${list}` });
+        /** Read the list, pause, write the list back changed: the lost-update window of every list-on-parent API. */
+        const rewrite = async (list, change) => {
+            const before = [...(cloud.lists.get(list) ?? [])];
+            if (cloud.listLatencyMs)
+                await sleep(Math.random() * cloud.listLatencyMs);
+            cloud.lists.set(list, change(before));
+        };
+        return {
+            outputs: {},
+            lockOn: (p) => (cloud.lockLists ? `fake:list:${String(p.list)}` : null),
+            async read(_actx, p) {
+                cloud.reads++;
+                const list = String(p.list);
+                const v = String(p.value);
+                return cloud.lists.get(list)?.includes(v) ? { resources: [record(list, v)], outputs: {} } : null;
+            },
+            diff(live, p) {
+                const v = String(p.value);
+                const exists = live?.resources.some((r) => r.key === key(String(p.list), v));
+                return [{ key: key(String(p.list), v), label: `${v} in ${String(p.list)}`, kind: exists ? "unchanged" : "create", ...(exists ? {} : { after: { state: "literal", value: v } }) }];
+            },
+            async apply(actx, p, live) {
+                const list = String(p.list);
+                const v = String(p.value);
+                if (live)
+                    return { resources: [record(list, v)], outputs: {}, created: [] };
+                await actx.intend([key(list, v)]);
+                cloud.maybeFail("create", v);
+                await rewrite(list, (values) => (values.includes(v) ? values : [...values, v]));
+                cloud.writes.push({ op: "create", name: `${list}/${v}` });
+                cloud.maybeFail("lost", v); // the write happened; the response did not arrive
+                return { resources: [record(list, v)], outputs: {}, created: [key(list, v)] };
+            },
+            async destroy(_actx, resources) {
+                for (const r of resources) {
+                    const at = r.id.indexOf("/");
+                    const [list, v] = [r.id.slice(0, at), r.id.slice(at + 1)];
+                    cloud.maybeFail("destroy", v);
+                    await rewrite(list, (values) => values.filter((x) => x !== v));
+                    cloud.writes.push({ op: "delete", name: r.id });
+                }
             },
         };
     }

package/dist/testing/fake.js.map

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

package/dist/types.d.ts

@@ -100,6 +100,16 @@ export interface OutputSpec {
     event?: string;
     /** Sensitive outputs are never displayed, logged, or written to receipts. */
     sensitive?: boolean;
+    /**
+     * The provider reveals this value only in the response that creates the resource (a database password's
+     * plaintext): `read` never returns it and Sponson never stores it, so declare it `sensitive` too. It reaches
+     * dependent lines in the run that creates the resource. In any later run, a `from:` reference to it resolves to
+     * `{ keep: true }` when the ledger's fingerprints show the dependent already holds the current value; a dependent
+     * that would have to write it (or cannot be shown to hold it) is refused with OUTPUT_UNAVAILABLE instead of
+     * receiving an empty value. Nothing is re-created to get the value back unless the run asks for it (`recreate`).
+     * See docs/adr/0018-once-only-outputs.md.
+     */
+    once?: boolean;
 }
 /** One concrete thing in the provider. */
 export interface ResourceRecord {
@@ -135,8 +145,8 @@ export interface LiveState {
     /** Outputs derivable from live state right now. Sensitive ones are still returned here; the engine masks them. */
     outputs: Record<string, Literal>;
 }
-/** What apply would do to one resource. */
-export type DiffKind = "create" | "update" | "unchanged";
+/** What apply would do to one resource; `run`: send a one-off action (`OpSpec.action`, ADR 0022). */
+export type DiffKind = "create" | "update" | "unchanged" | "run";
 /**
  * One side of a diff, as data. Renderers turn it into text; JSON carries it as-is.
  * `value` is present only for non-sensitive literal values; everything else is described by state.
@@ -191,6 +201,13 @@ export interface AdapterContext {
     intend(keys: string[]): Promise<void>;
     /** Mask every known secret (in all its encodings). Call it on provider text BEFORE truncating it. */
     redact(text: string): string;
+    /**
+     * Register a credential the adapter obtained at run time (an OAuth access token, a token printed by a CLI), so
+     * that it is masked in every output, receipt and error from now on, exactly like a resolved secret. Optional: a
+     * context without it (an older engine, a test harness) masks nothing more, so adapters also mask such values in
+     * their own error text.
+     */
+    secret?(value: string): void;
 }
 /**
  * One plan line proposed by `OpSpec.adopt`. The CLI adds `adapter`, `op` and `environments`, and makes `id` unique.
@@ -219,14 +236,78 @@ export interface AdoptedLine {
  */
 export interface OpSpec {
     outputs: Record<string, OutputSpec>;
+    /**
+     * For ops whose outputs a line declares in its own params (the generic `http` ops): the outputs of one line,
+     * given its params as written (not interpolated, references unresolved). The engine uses them instead of
+     * `outputs` for that line, so a `from:` naming an undeclared output still fails before any provider call. Throw
+     * PARAM_INVALID for a malformed declaration.
+     */
+    outputsFor?(params: Record<string, unknown>): Record<string, OutputSpec>;
+    /**
+     * For ops whose `providers.<adapter>` block holds several independent configurations (the generic `http`
+     * adapter: one per API): the part a line uses, given the whole block and the line's params as written. It
+     * becomes `actx.provider` and part of the ledger identity of the line's resources, so editing one API's
+     * configuration does not re-identify resources of another. Pure; throw PLAN_INVALID when the line names a
+     * configuration the block does not have. Without it the whole block is used.
+     */
+    providerFor?(block: Record<string, unknown>, params: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * The names of the line's params that carry a credential the op authenticates with (the generic `http` adapter's
+     * line-level `credential`), given the params as written. The engine checks each before any provider call: it must
+     * be a `{ secret: … }` reference, or a `{ from: <line>.<output> }` naming an output declared `sensitive` and not
+     * `once` (a once-only value resolves to `{ keep: true }` in later runs, which cannot authenticate a request);
+     * anything else, a literal above all, is PARAM_INVALID. The resolved value is masked like any secret. Pure.
+     */
+    credentialInputs?(params: Record<string, unknown>): string[];
     /** Fill in defaults (e.g. a branch name) given the context. Returns a new params object. */
     defaults?(params: ResolvedParams, ctx: Ctx): ResolvedParams;
     /**
-     * The deployment environment this change writes to, when the op targets one explicitly
-     * (Vercel env `target`). The engine requires approval when any line writes to `production`,
-     * whatever the run's environment is. Return null when the op is not environment-specific.
+     * The deployment environment this change writes to, when the op targets one explicitly: from the line's params
+     * (Vercel env `target`) or from the provider block the line writes through (`provider`, the `providers.<adapter>`
+     * block as `providerFor` narrows it: a LaunchDarkly block naming a production environment). The engine requires
+     * approval when any line writes to `production`, whatever the run's environment is. Return null when the op is not
+     * environment-specific. Pure, called before any provider call; throw PLAN_INVALID for a block it cannot judge.
+     * The engine always passes `provider`; it is optional only so that callers written for the two-argument form
+     * still compile.
      */
-    writesEnvironment?(params: ResolvedParams, ctx: Ctx): string | null;
+    writesEnvironment?(params: ResolvedParams, ctx: Ctx, provider?: Record<string, unknown>): string | null;
+    /**
+     * The shared provider object this line's resources live in, when its writes are read-modify-write of something
+     * other scopes write too: one callback array on an Auth0 application, Supabase's `uri_allow_list`, a Firebase
+     * authorized-domains list. Return a stable identity naming the provider, the account and the object, e.g.
+     * `auth0:<tenant>:client:<client id>`; null when the line's resources are objects of their own.
+     *
+     * The engine then holds a lease on that identity (ADR 0019) across scopes and environments around every write the
+     * line makes: re-reading live state, `apply`, and the `destroy` of rollback and `apply --destroy` (which use the
+     * identity recorded in the ledger, so a line removed from the plan is still locked correctly). The identity is
+     * written to receipts and shown in messages: never put a secret in it. Pure: no provider calls.
+     */
+    lockOn?(params: ResolvedParams, provider: Record<string, unknown>): string | null;
+    /**
+     * For an op whose change a person makes, not an API (the built-in `manual.step`, ADR 0021): the step as the human
+     * sees it, from resolved params; null while an input is still pending. The engine then owns the line's state:
+     * `plan` shows it as `todo` with these instructions until it is done, `apply` records it only when the run
+     * confirms it (`RunOptions.confirm`) or `read` observes it (a verify request), and otherwise leaves it waiting
+     * with MANUAL_STEP_PENDING; `apply --destroy` shows `undo` and needs the same confirmation. `read` returns the
+     * step's resource only when it can observe that the step is done (`observable`), else null; `apply` and
+     * `destroy` are never called. Pure: no provider calls.
+     */
+    manual?(params: ResolvedParams, ctx: Ctx): ManualStep | null;
+    /**
+     * For an op that is a one-off action rather than a resource (the built-in `http.action`, ADR 0022: an Inngest
+     * sync, a cache purge, a deploy notification): its trigger, from resolved params; null while a trigger value is
+     * still pending. The engine then owns the line's state. The ledger key is `action:<line id>` and its hash the
+     * keyed `sha256(canonicalJson(trigger))`: `plan` shows `run` when no run of this trigger is recorded and
+     * `unchanged` otherwise, with no other drift. `apply` calls `apply` only to run it, passing as `live` one resource
+     * (the ledger key, the previous record id or "", and the raw trigger hash, from which the op derives an
+     * idempotency key), then records the trigger hash, the record id `apply` returned (`resources[0].id`: how to undo
+     * it) and the outputs. Nothing is recorded before the request is sent (at-least-once: a crash in between sends it
+     * again with the same idempotency key), `intend` is never called, rollback never undoes it, and another scope's
+     * record of the same key does not block it. `apply --destroy` passes the record to `destroy` (send the undo, or
+     * nothing) and forgets it. `read` is never called. Outputs must not be sensitive: an unchanged line's outputs come
+     * from the ledger. Pure: no provider calls.
+     */
+    action?(params: ResolvedParams, ctx: Ctx): ActionTrigger | null;
     /** Find what currently exists for this change. Null when nothing exists. Must not write. */
     read(actx: AdapterContext, params: ResolvedParams): Promise<LiveState | null>;
     /**
@@ -269,6 +350,27 @@ export interface OpSpec {
         id?: string;
     }>, ctx: Ctx): AdoptedLine[];
 }
+/** One step a person must do by hand, as `OpSpec.manual` describes it (ADR 0021). */
+export interface ManualStep {
+    /** The resource key: stable for the step, whatever its instructions say (`step:<title>`). */
+    key: string;
+    title: string;
+    /** What to do, as Markdown, with every reference already filled in. */
+    instructions: string;
+    /** What to do to reverse it when the scope is destroyed, as Markdown; absent when there is nothing to undo. */
+    undo?: string;
+    /** Hash of what the person is asked to do (`sha256(canonicalJson({ title, instructions }))`): a new one is a new step. */
+    hash: string;
+    /** Whether `read` can observe that the step is done (a verify request); otherwise only a confirmation can tell. */
+    observable: boolean;
+}
+/** The trigger of a one-off action, as `OpSpec.action` describes it (ADR 0022). */
+export interface ActionTrigger {
+    /** The values whose change makes the action run again (a commit, a preview URL), resolved; hashed, never stored. */
+    trigger: Record<string, unknown>;
+    /** What the action does, for display (`PUT https://…/api/inngest`). */
+    label: string;
+}
 /**
  * A provider integration: a name (the plan's `adapter:`) and its ops. Register it with `Registry.addAdapter`;
  * see `OpSpec` for the contract and `@sponson/core/testing` for a complete in-memory adapter.
@@ -317,10 +419,48 @@ export interface ResourceAdapter {
 }
 /** The environment an adapter reads: its credential, and the variable that overrides its API base URL. */
 export interface AdapterAbout {
-    /** Environment variable holding the credential, e.g. `NEON_API_KEY`. */
+    /**
+     * Environment variable holding the credential, e.g. `NEON_API_KEY`; for an adapter whose plan names the
+     * variable per provider block (the generic `http` adapter), where in the plan it is named.
+     */
     credentialEnv: string;
-    /** Environment variable that overrides the API base URL (the sim and tests use it), when there is one. */
+    /** Environment variable that overrides the API base URL (the sim and tests use it), when there is one; or where the plan names it. */
     baseUrlEnv?: string;
+    /** Further variables the credential needs, when one is not enough (PlanetScale: the service token's id). */
+    extraCredentialEnv?: readonly string[];
+    /**
+     * The command whose output is the credential, for an adapter that takes a CLI's access token instead of reading a
+     * variable (Cloud Run: `gcloud auth print-access-token`). `credentialEnv` then names the command for people, and no
+     * variable is listed as the credential.
+     */
+    credentialCommand?: readonly string[];
+    /** The provider as people write it (Vercel, Cloudflare Pages): `sponson init`'s summary and the provider catalog. */
+    title?: string;
+    /** The id of the docs/coverage.yaml category the adapter belongs to (deploy, databases, auth, …). */
+    category?: string;
+    /**
+     * What in a repository's files says it uses this provider. `sponson init` reads it to detect the provider, so an
+     * adapter that declares it is detected with no change to the CLI. Absent for adapters no repository file names
+     * (the generic `http` adapter, `manual`).
+     */
+    detect?: ProviderDetect;
+}
+/**
+ * The signals `sponson init` detects a provider by: names and files only. The value of a variable is never read,
+ * except a database URL's host, which is classified against `dbHosts` and dropped.
+ */
+export interface ProviderDetect {
+    /** Dependency names in package.json: exact (`stripe`), or a scope or prefix ending in `/` (`@stripe/`). */
+    deps?: readonly string[];
+    /**
+     * Variable names in `.env*` files: exact (`AUTH0_DOMAIN`), or a prefix ending in `*` (`AUTH0_*`). A framework's
+     * public prefix (`NEXT_PUBLIC_`, `PUBLIC_`, `VITE_`, …) in front of the name matches too.
+     */
+    env?: readonly string[];
+    /** Files whose presence is a signal (`fly.toml`), relative to the repository root. */
+    files?: readonly string[];
+    /** Host suffixes (`.neon.tech`) of a database URL in an `.env*` file that point at this provider. */
+    dbHosts?: readonly string[];
 }
 /**
  * Resolves `{ secret: "<scheme>://..." }` references. Register one with `Registry.addSecretSource` to support a
@@ -391,6 +531,34 @@ export interface LedgerEntry {
     orphan?: boolean;
     /** Non-sensitive outputs last seen for the owning line (including external ones like preview_url). */
     outputs?: Record<string, Literal>;
+    /** The shared parent object the resource lives in (`OpSpec.lockOn`); rollback and destroy lock it (ADR 0019). */
+    parent?: string;
+    /**
+     * Keyed fingerprints of the `once` outputs (ADR 0018) the line's create returned, by output name: which value is
+     * current, never the value.
+     */
+    onceFingerprints?: Record<string, string>;
+    /**
+     * Keyed fingerprints of the `once` values this resource was last written with, by reference (`line.output`). Equal
+     * to the producer's `onceFingerprints` entry means it still holds the current value (ADR 0018).
+     */
+    onceInputs?: Record<string, string>;
+    /**
+     * For a manual step (ADR 0021): what it was and how it was found done. `undo` is what `apply --destroy` asks a
+     * person to do; `by` and `at` say who confirmed it and when (`how: confirmed`), or when a verify request first
+     * saw it done (`how: verified`). Text is stored masked, as every output is.
+     */
+    manual?: {
+        title: string;
+        undo?: string;
+        how: "confirmed" | "verified";
+        by?: string;
+        at: string;
+    };
+    /** For a one-off action (ADR 0022): when it last ran. `hash` is its trigger's; `id` says how to undo it. */
+    action?: {
+        at: string;
+    };
 }
 /**
  * The record of one run for an environment and scope, and the ledger it leaves behind. Stores persist it; agents
@@ -463,6 +631,20 @@ export interface ReceiptStore {
     /** Current lock, or null. Never throws for a missing/unreadable lock. */
     readLock(environment: string, scope: string): Promise<LockInfo | null>;
     releaseLock(environment: string, scope: string, holder: string): Promise<void>;
+    /**
+     * Parent-object locks (ADR 0019): a lease on a shared provider object (`OpSpec.lockOn`), one per object across
+     * every scope and environment, with the same semantics as the scope lock (`LockHeldError`, expiry and takeover,
+     * `LockLostError` on a renewal by someone who lost it). `parent` is the identity the op returned; stores key it by
+     * `parentLockScope(parent)`. Optional: the engine falls back to the scope-lock methods under the reserved
+     * environment `PARENT_LOCKS_ENVIRONMENT`, which every store supports.
+     */
+    acquireParentLock?(parent: string, holder: string, ttlMs: number): Promise<LockInfo | null>;
+    /** Extend a parent lock we hold. Throws LockLostError when someone else holds it now. */
+    renewParentLock?(parent: string, holder: string, ttlMs: number): Promise<void>;
+    /** Current parent lock, or null. Never throws for a missing/unreadable lock. */
+    readParentLock?(parent: string): Promise<LockInfo | null>;
+    /** Release a parent lock; a no-op when `holder` does not hold it. */
+    releaseParentLock?(parent: string, holder: string): Promise<void>;
     /** Release what the store holds locally (a temporary working clone). Whoever constructed the store calls it once done. */
     close?(): Promise<void>;
 }

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAgCH,0GAA0G;AAC1G,MAAM,UAAU,SAAS,CAAC,CAAU;IAClC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,MAAM,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC;AAC1F,CAAC;AAED,iCAAiC;AACjC,MAAM,UAAU,SAAS,CAAC,CAAU;IAClC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC;AAC/E,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,WAAW,CAAC,CAAU;IACpC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,QAAQ,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC;AAC9F,CAAC;AAmdD,sGAAsG;AACtG,MAAM,OAAO,aAAc,SAAQ,KAAK;IACV;IAAgC;IAA5D,YAA4B,MAAc,EAAkB,OAAwB;QAClF,KAAK,CAAC,4CAA4C,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAD9E,WAAM,GAAN,MAAM,CAAQ;QAAkB,YAAO,GAAP,OAAO,CAAiB;QAElF,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,0EAA0E;AAC1E,MAAM,OAAO,aAAc,SAAQ,KAAK;IACV;IAA5B,YAA4B,IAAc;QACxC,KAAK,CAAC,sBAAsB,IAAI,CAAC,MAAM,UAAU,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;QADzC,SAAI,GAAJ,IAAI,CAAU;QAExC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAgCH,0GAA0G;AAC1G,MAAM,UAAU,SAAS,CAAC,CAAU;IAClC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,MAAM,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC;AAC1F,CAAC;AAED,iCAAiC;AACjC,MAAM,UAAU,SAAS,CAAC,CAAU;IAClC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC;AAC/E,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,WAAW,CAAC,CAAU;IACpC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,QAAQ,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC;AAC9F,CAAC;AAooBD,sGAAsG;AACtG,MAAM,OAAO,aAAc,SAAQ,KAAK;IACV;IAAgC;IAA5D,YAA4B,MAAc,EAAkB,OAAwB;QAClF,KAAK,CAAC,4CAA4C,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAD9E,WAAM,GAAN,MAAM,CAAQ;QAAkB,YAAO,GAAP,OAAO,CAAiB;QAElF,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,0EAA0E;AAC1E,MAAM,OAAO,aAAc,SAAQ,KAAK;IACV;IAA5B,YAA4B,IAAc;QACxC,KAAK,CAAC,sBAAsB,IAAI,CAAC,MAAM,UAAU,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;QADzC,SAAI,GAAJ,IAAI,CAAU;QAExC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sponson/core",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Plan model, planner, execution engine, receipt stores and adapter interfaces for Sponson.",
   "keywords": [
     "sponson",
@@ -47,6 +47,10 @@
     "README.md",
     "LICENSE"
   ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "homepage": "https://sponson.mintlify.site",
   "bugs": {
     "url": "https://github.com/MishaBear94/Sponson/issues"