@irogane/kaji 0.2.0-beta.11 → 0.3.0

package/dist/index.d.mts

@@ -0,0 +1,253 @@
+//#region src/execution-context.d.ts
+/**
+ * The information a capability's `execute` function needs to run safely.
+ *
+ * This stays intentionally small: no store, registry, session, or engine
+ * reference. Identity is exactly `principalId`. Cancellation uses the
+ * platform's native `AbortSignal` instead of a Kaji-specific token.
+ */
+type ExecutionContext = {
+  readonly principalId: string;
+  readonly idempotencyKey: string;
+  readonly signal: AbortSignal;
+};
+//#endregion
+//#region src/schema.d.ts
+/**
+ * Kaji stays validator-neutral. `input` needs only a `parse` method that
+ * returns validated input or throws, per docs/api.md: "input needs only a
+ * parser that either returns validated input or throws." Zod, Valibot (via
+ * `.parse`), and other libraries satisfy this shape without an adapter.
+ */
+type InputParser<Output> = {
+  parse(input: unknown): Output;
+};
+//#endregion
+//#region src/capability.d.ts
+/**
+ * A request to authorize or require approval for one capability execution.
+ * Kept inline rather than named because it is not part of the store contract
+ * and does not need to be constructed by callers.
+ */
+type PrincipalRequest<Input> = {
+  readonly principalId: string;
+  readonly input: Input;
+};
+/**
+ * Declares one application action: its validated input contract,
+ * authorization/approval rules, and the function Kaji will eventually
+ * execute. A capability does not execute itself; `feat/execute` owns that.
+ *
+ * `Input` is the parser's returned/validated type, matching what
+ * `authorize`, `approval`, and `execute` receive.
+ */
+type CapabilityDefinition<Input, Result> = {
+  readonly name: string;
+  readonly input: InputParser<Input>;
+  readonly authorize: (request: PrincipalRequest<Input>) => boolean | Promise<boolean>;
+  readonly approval?: (request: PrincipalRequest<Input>) => boolean;
+  readonly execute: (input: Input, context: ExecutionContext) => Result | Promise<Result>;
+};
+/**
+ * The declared capability, as frozen by docs/api.md.
+ *
+ * Only `name` is public today. `Input` and `Result` are retained as type
+ * parameters (unused at this field) because a future `Kaji.execute()` needs
+ * `Capability<Input, Result>` to recover both types; removing them now would
+ * force `feat/execute` to redesign this type. The unused-type-parameter
+ * warning this produces is suppressed in .oxlintrc.json for this file.
+ */
+type Capability<Input, Result> = {
+  readonly name: string;
+};
+/**
+ * Defines one application action that Kaji can later execute safely.
+ *
+ * `capability()` is the single canonical constructor. It validates its own
+ * declaration (name, hooks) at construction time; it never invokes
+ * `authorize`, `approval`, or `execute` itself.
+ */
+declare function capability<Input, Result>(definition: CapabilityDefinition<Input, Result>): Capability<Input, Result>;
+//#endregion
+//#region src/approval.d.ts
+/**
+ * What Kaji tells an application's `approve` handler about one request
+ * requiring approval, per docs/api.md's inline `createKaji()` contract.
+ * Not exported: docs/api.md keeps this shape inline in `KajiOptions`
+ * rather than naming it, so there is no caller need to import it directly.
+ */
+type ApprovalRequest = {
+  readonly capability: string;
+  readonly principalId: string;
+  readonly input: unknown;
+  readonly idempotencyKey: string;
+};
+/** What an application's `approve` handler returns for one request. */
+type ApprovalDecision = {
+  readonly approved: boolean;
+  readonly evidence?: unknown;
+};
+type ApproveHandler = (request: ApprovalRequest) => ApprovalDecision | Promise<ApprovalDecision>;
+//#endregion
+//#region src/execution-request.d.ts
+/**
+ * One caller's request to run a capability, as frozen by docs/api.md.
+ * `principalId` and `idempotencyKey` are supplied by the caller — Kaji
+ * never infers either from process state (docs/invariants.md
+ * "Principal is explicit").
+ */
+type ExecutionRequest = {
+  readonly input: unknown;
+  readonly principalId: string;
+  readonly idempotencyKey: string;
+  readonly signal?: AbortSignal;
+};
+//#endregion
+//#region src/execution-result.d.ts
+/**
+ * The minimal facts Kaji knows about one governed execution.
+ *
+ * This is deliberately not a general event or audit record: it carries only
+ * what a caller needs to identify the execution and detect conflicting
+ * idempotency key reuse. See docs/invariants.md "Evidence is minimal".
+ */
+type ExecutionEvidence = {
+  readonly executionId: string;
+  readonly capability: string;
+  readonly principalId: string;
+  readonly idempotencyKey: string;
+  readonly inputFingerprint: string;
+};
+/**
+ * The explicit outcome of one governed execution, as frozen by docs/api.md.
+ *
+ * `unknown` is distinct from `failed`: it means the capability's side effect
+ * may have committed but Kaji cannot prove the final result, so callers
+ * must not treat it as an ordinary retryable failure.
+ */
+type ExecutionResult<Result> = {
+  readonly status: "succeeded";
+  readonly result: Result;
+  readonly evidence: ExecutionEvidence;
+} | {
+  readonly status: "denied" | "rejected" | "failed" | "cancelled";
+  readonly error: unknown;
+  readonly evidence: ExecutionEvidence;
+} | {
+  readonly status: "unknown";
+  readonly error: unknown;
+  readonly evidence: ExecutionEvidence;
+};
+//#endregion
+//#region src/execution-store.d.ts
+/**
+ * The material identity of one intended operation: which capability, which
+ * principal, which caller-supplied idempotency key, and a fingerprint of
+ * the validated input. The store uses this tuple to detect duplicate
+ * claims and conflicting reuse; it never sees the raw input or the
+ * capability's callbacks.
+ */
+type ExecutionClaim = {
+  readonly capability: string;
+  readonly principalId: string;
+  readonly idempotencyKey: string;
+  readonly inputFingerprint: string;
+};
+/** The terminal or in-flight record a store persists for one execution. */
+type StoredExecution = ExecutionResult<unknown>;
+/**
+ * The outcome of attempting to claim one execution.
+ *
+ * `"existing"` covers both an execution still running and one already
+ * settled: its `outcome` promise resolves once the claim is recorded,
+ * so a caller that must not duplicate a side effect can simply await it
+ * instead of the store exposing separate running/completed/unknown states.
+ */
+type ClaimResult = {
+  readonly status: "claimed";
+  readonly executionId: string;
+} | {
+  readonly status: "existing";
+  readonly outcome: Promise<StoredExecution>;
+} | {
+  readonly status: "conflict";
+  readonly executionId: string;
+};
+/**
+ * Persists execution identity, idempotency claims, and minimal outcome
+ * evidence. A store does not execute capabilities, enforce authorization
+ * or approval, or decide retries — it only answers whether an execution
+ * may begin and records what happened once it is known.
+ *
+ * `claim()` must be atomic enough that concurrent claims for the same
+ * identity produce exactly one `"claimed"` result; see docs/invariants.md
+ * "Store semantics are atomic where required".
+ */
+type ExecutionStore = {
+  claim(claim: ExecutionClaim): Promise<ClaimResult>;
+  record(execution: StoredExecution): Promise<void>;
+};
+//#endregion
+//#region src/kaji.d.ts
+/** Stable application configuration for the executor, per docs/api.md. */
+type KajiOptions = {
+  readonly store: ExecutionStore;
+  readonly approve?: ApproveHandler;
+  readonly timeoutMs?: number;
+};
+/** The Kaji executor, as frozen by docs/api.md. */
+type Kaji = {
+  execute<Input, Result>(capability: Capability<Input, Result>, request: ExecutionRequest): Promise<ExecutionResult<Result>>;
+};
+/**
+ * Creates the Kaji executor: the one canonical entry point for running a
+ * capability. `kaji.execute()` validates the request, claims its
+ * idempotency key, authorizes and approves it, calls the capability at
+ * most once, and records the explicit outcome.
+ */
+declare function createKaji(options: KajiOptions): Kaji;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Marks a capability's `execute` failure as definitively known rather than
+ * ambiguous: application code is asserting that no side effect committed,
+ * so Kaji may settle `failed` instead of its safe `unknown` default. See
+ * docs/invariants.md "Ambiguous outcomes are preserved" and "Known failure
+ * is explicit".
+ *
+ * `knownFailure()` is the only way to opt out of `unknown`. Kaji never
+ * infers this from an error's class, message, or status code — only
+ * application code that actually knows the remote side effect did not
+ * commit may make this claim.
+ */
+declare class KnownFailure extends Error {
+  constructor(cause: unknown);
+}
+/**
+ * Wraps `cause` so a capability's `execute` function can throw it to
+ * report an ordinary, provably non-ambiguous failure (docs/api.md).
+ *
+ * Usage:
+ * ```ts
+ * execute: async (input, context) => {
+ *   try {
+ *     return await provider.charge(input);
+ *   } catch (cause) {
+ *     if (isDefinitelyDeclined(cause)) throw knownFailure(cause);
+ *     throw cause; // stays unknown: the side effect may have committed
+ *   }
+ * },
+ * ```
+ */
+declare function knownFailure(cause: unknown): KnownFailure;
+//#endregion
+//#region src/memory-store.d.ts
+/**
+ * A process-local reference `ExecutionStore`. It has no external
+ * persistence, no cross-process visibility, and no durability guarantee —
+ * it exists for development, tests, and examples, but honors the same
+ * claim/record contract a durable store must honor.
+ */
+declare function memoryStore(): ExecutionStore;
+//#endregion
+export { type Capability, type ClaimResult, type ExecutionClaim, type ExecutionContext, type ExecutionEvidence, type ExecutionRequest, type ExecutionResult, type ExecutionStore, type StoredExecution, capability, createKaji, knownFailure, memoryStore };

package/dist/index.mjs

@@ -0,0 +1,440 @@
+//#region src/capability.ts
+/**
+* Defines one application action that Kaji can later execute safely.
+*
+* `capability()` is the single canonical constructor. It validates its own
+* declaration (name, hooks) at construction time; it never invokes
+* `authorize`, `approval`, or `execute` itself.
+*/
+function capability(definition) {
+	const name = definition.name;
+	if (typeof name !== "string" || name.trim().length === 0) throw new Error("capability() requires a non-empty name.");
+	if (typeof definition.authorize !== "function") throw new Error("capability() requires an authorize function.");
+	return Object.freeze({
+		name,
+		input: definition.input,
+		authorize: definition.authorize,
+		approval: definition.approval,
+		execute: definition.execute
+	});
+}
+/**
+* Recovers the full declaration from a `Capability`. The public
+* `Capability<Input, Result>` type only advertises `name`, but the object
+* `capability()` returns always carries `input`/`authorize`/`approval`/
+* `execute` — the executor is their one legitimate reader.
+*/
+function capabilityDefinition(capability$1) {
+	return capability$1;
+}
+
+//#endregion
+//#region src/approval.ts
+/**
+* Resolves whether a request that requires approval may proceed.
+*
+* Approval is fail-closed (docs/invariants.md "Approval is fail-closed"):
+* a missing handler, an invalid decision shape, a rejected decision, or a
+* thrown/rejected handler all prevent execution. Only an explicit
+* `{ approved: true }` allows the caller to continue.
+*/
+async function resolveApproval(approve, request) {
+	if (approve === void 0) return {
+		approved: false,
+		error: /* @__PURE__ */ new Error("Approval is required but no approve handler was configured.")
+	};
+	let decision;
+	try {
+		decision = await approve(request);
+	} catch (cause) {
+		return {
+			approved: false,
+			error: cause
+		};
+	}
+	if (typeof decision !== "object" || decision === null || typeof decision.approved !== "boolean") return {
+		approved: false,
+		error: /* @__PURE__ */ new Error("approve() returned an invalid decision; expected { approved: boolean }.")
+	};
+	if (!decision.approved) return {
+		approved: false,
+		error: /* @__PURE__ */ new Error("Approval was not granted.")
+	};
+	return {
+		approved: true,
+		evidence: decision.evidence
+	};
+}
+
+//#endregion
+//#region src/effective-signal.ts
+/**
+* Combines the caller's signal (if any) with Kaji's optional `timeoutMs`
+* into one effective `AbortSignal`, using only native `AbortSignal`/
+* `AbortController` primitives (docs/invariants.md "Native primitives
+* first"). `cleanup()` must be called once execution finishes so the
+* timeout timer does not keep the process alive.
+*/
+function effectiveSignal(callerSignal, timeoutMs) {
+	if (timeoutMs === void 0) return {
+		signal: callerSignal ?? new AbortController().signal,
+		cleanup: () => {}
+	};
+	const timeoutController = new AbortController();
+	const timer = setTimeout(() => timeoutController.abort(), timeoutMs);
+	return {
+		signal: callerSignal === void 0 ? timeoutController.signal : AbortSignal.any([callerSignal, timeoutController.signal]),
+		cleanup: () => clearTimeout(timer)
+	};
+}
+
+//#endregion
+//#region src/fingerprint.ts
+/**
+* Thrown when a value falls outside the durable value domain — plain
+* JSON-shaped data — and cannot be fingerprinted deterministically.
+* Capability input is schema-validated application data, so this is the
+* natural boundary: it excludes functions, symbols, and other values a
+* schema parser would not normally produce.
+*/
+var UnfingerprintableValueError = class extends Error {
+	constructor(reason) {
+		super(`Cannot fingerprint input: ${reason}`);
+		this.name = "UnfingerprintableValueError";
+	}
+};
+/**
+* Produces a deterministic string for one capability's validated input.
+*
+* Object key order must not affect the result — two semantically identical
+* inputs must fingerprint identically regardless of how their keys were
+* constructed — so this canonicalizes objects by sorting keys before
+* serializing, rather than relying on `JSON.stringify`'s insertion order.
+*/
+function fingerprintInput(capability$1, input) {
+	return `${capability$1}:${canonicalize(input)}`;
+}
+function canonicalize(value) {
+	if (value === null) return "null";
+	if (typeof value === "string") return JSON.stringify(value);
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new UnfingerprintableValueError(`non-finite number ${value}`);
+		return JSON.stringify(value);
+	}
+	if (typeof value === "boolean") return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(canonicalize).join(",")}]`;
+	if (typeof value === "object") return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalize(value[key])}`).join(",")}}`;
+	throw new UnfingerprintableValueError(`unsupported value of type ${typeof value}`);
+}
+
+//#endregion
+//#region src/errors.ts
+/**
+* Thrown only when Kaji cannot establish the execution boundary at all —
+* an invalid executor configuration, or a store failure before any
+* execution record exists. Every other outcome (denied, rejected, failed,
+* cancelled, unknown) is an ordinary `ExecutionResult`, not a thrown error;
+* see docs/api.md "Results and outcomes".
+*/
+var KajiConfigurationError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "KajiConfigurationError";
+	}
+};
+/**
+* Marks a capability's `execute` failure as definitively known rather than
+* ambiguous: application code is asserting that no side effect committed,
+* so Kaji may settle `failed` instead of its safe `unknown` default. See
+* docs/invariants.md "Ambiguous outcomes are preserved" and "Known failure
+* is explicit".
+*
+* `knownFailure()` is the only way to opt out of `unknown`. Kaji never
+* infers this from an error's class, message, or status code — only
+* application code that actually knows the remote side effect did not
+* commit may make this claim.
+*/
+var KnownFailure = class extends Error {
+	constructor(cause) {
+		super("Capability execution failed with a definitively known outcome.", { cause });
+		this.name = "KnownFailure";
+	}
+};
+/**
+* Wraps `cause` so a capability's `execute` function can throw it to
+* report an ordinary, provably non-ambiguous failure (docs/api.md).
+*
+* Usage:
+* ```ts
+* execute: async (input, context) => {
+*   try {
+*     return await provider.charge(input);
+*   } catch (cause) {
+*     if (isDefinitelyDeclined(cause)) throw knownFailure(cause);
+*     throw cause; // stays unknown: the side effect may have committed
+*   }
+* },
+* ```
+*/
+function knownFailure(cause) {
+	return new KnownFailure(cause);
+}
+
+//#endregion
+//#region src/schema.ts
+/**
+* Validates unknown input against a capability's parser.
+*
+* This is the one canonical validation primitive in Kaji. The future
+* executor calls this exact function so there is never a second path that
+* could let invalid input reach application code.
+*/
+function validateInput(parser, input) {
+	return parser.parse(input);
+}
+
+//#endregion
+//#region src/execute.ts
+/**
+* Runs the one canonical Kaji execution path for one request, in the exact
+* order docs/api.md freezes: validate, claim idempotency, authorize,
+* obtain approval when needed, execute, and record the explicit outcome.
+*
+* Claiming before authorization is deliberate: claiming an idempotency key
+* is bookkeeping, not the side effect docs/invariants.md's "Authorization
+* precedes side effects" protects. It lets a denied or rejected request
+* still occupy and settle its idempotency key, so a caller who retries a
+* denied request with the same key observes the same denial instead of a
+* fresh authorization check racing a duplicate claim.
+*/
+async function executeCapability(dependencies, capability$1, request) {
+	const definition = capabilityDefinition(capability$1);
+	const principalId = requireNonEmptyString(request.principalId, "principalId");
+	const idempotencyKey = requireNonEmptyString(request.idempotencyKey, "idempotencyKey");
+	const { signal, cleanup } = effectiveSignal(request.signal, dependencies.timeoutMs);
+	try {
+		if (signal.aborted) return cancelled(capability$1.name, principalId, idempotencyKey);
+		const input = validateInput(definition.input, request.input);
+		const inputFingerprint = fingerprintInput(capability$1.name, input);
+		const claimResult = await claim(dependencies.store, {
+			capability: capability$1.name,
+			principalId,
+			idempotencyKey,
+			inputFingerprint
+		});
+		if (claimResult.status === "conflict") return conflict(capability$1.name, principalId, idempotencyKey, claimResult.executionId, inputFingerprint);
+		if (claimResult.status === "existing") return await claimResult.outcome;
+		const evidence = {
+			executionId: claimResult.executionId,
+			capability: capability$1.name,
+			principalId,
+			idempotencyKey,
+			inputFingerprint
+		};
+		if (signal.aborted) return await settle(dependencies.store, cancelled(capability$1.name, principalId, idempotencyKey, evidence));
+		const authorization = await guarded(() => definition.authorize({
+			principalId,
+			input
+		}));
+		if (!authorization.ok) return await settle(dependencies.store, denied(evidence, authorization.error));
+		if (authorization.value === false) return await settle(dependencies.store, denied(evidence, /* @__PURE__ */ new Error("Authorization denied the request.")));
+		if (signal.aborted) return await settle(dependencies.store, cancelled(capability$1.name, principalId, idempotencyKey, evidence));
+		if (definition.approval?.({
+			principalId,
+			input
+		}) === true) {
+			const decision = await resolveApproval(dependencies.approve, {
+				capability: capability$1.name,
+				principalId,
+				input,
+				idempotencyKey
+			});
+			if (!decision.approved) return await settle(dependencies.store, rejected(evidence, decision.error));
+		}
+		if (signal.aborted) return await settle(dependencies.store, cancelled(capability$1.name, principalId, idempotencyKey, evidence));
+		const context = {
+			principalId,
+			idempotencyKey,
+			signal
+		};
+		const outcome = await runCapability(definition.execute, input, context, evidence);
+		return await settle(dependencies.store, outcome);
+	} finally {
+		cleanup();
+	}
+}
+async function runCapability(execute, input, context, evidence) {
+	try {
+		return {
+			status: "succeeded",
+			result: await execute(input, context),
+			evidence
+		};
+	} catch (cause) {
+		if (cause instanceof KnownFailure) return {
+			status: "failed",
+			error: cause.cause,
+			evidence
+		};
+		return {
+			status: "unknown",
+			error: cause,
+			evidence
+		};
+	}
+}
+async function claim(store, executionClaim) {
+	try {
+		return await store.claim(executionClaim);
+	} catch (cause) {
+		throw new KajiConfigurationError("Execution store failed to claim the operation.", { cause });
+	}
+}
+/**
+* Persists a terminal outcome and returns it. A store failure here means
+* Kaji cannot prove the outcome was durably recorded; docs/invariants.md
+* requires that ambiguity to surface as `unknown` rather than the
+* capability's real outcome, since a caller could otherwise be told an
+* action succeeded that Kaji has no durable record of.
+*/
+async function settle(store, outcome) {
+	try {
+		await store.record(outcome);
+		return outcome;
+	} catch (cause) {
+		return {
+			status: "unknown",
+			error: cause,
+			evidence: outcome.evidence
+		};
+	}
+}
+async function guarded(fn) {
+	try {
+		return {
+			ok: true,
+			value: await fn()
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error
+		};
+	}
+}
+function denied(evidence, error) {
+	return {
+		status: "denied",
+		error,
+		evidence
+	};
+}
+function rejected(evidence, error) {
+	return {
+		status: "rejected",
+		error,
+		evidence
+	};
+}
+function conflict(capability$1, principalId, idempotencyKey, executionId, inputFingerprint) {
+	return {
+		status: "failed",
+		error: /* @__PURE__ */ new Error(`Idempotency key "${idempotencyKey}" was already used for a different request.`),
+		evidence: {
+			executionId,
+			capability: capability$1,
+			principalId,
+			idempotencyKey,
+			inputFingerprint
+		}
+	};
+}
+function cancelled(capability$1, principalId, idempotencyKey, evidence) {
+	return {
+		status: "cancelled",
+		error: /* @__PURE__ */ new Error("Execution was cancelled before it began."),
+		evidence: evidence ?? {
+			executionId: "",
+			capability: capability$1,
+			principalId,
+			idempotencyKey,
+			inputFingerprint: ""
+		}
+	};
+}
+function requireNonEmptyString(value, field) {
+	if (typeof value !== "string" || value.trim().length === 0) throw new KajiConfigurationError(`ExecutionRequest.${field} must be a non-empty string.`);
+	return value;
+}
+
+//#endregion
+//#region src/kaji.ts
+/**
+* Creates the Kaji executor: the one canonical entry point for running a
+* capability. `kaji.execute()` validates the request, claims its
+* idempotency key, authorizes and approves it, calls the capability at
+* most once, and records the explicit outcome.
+*/
+function createKaji(options) {
+	return { execute(capability$1, request) {
+		return executeCapability(options, capability$1, request);
+	} };
+}
+
+//#endregion
+//#region src/memory-store.ts
+/**
+* A process-local reference `ExecutionStore`. It has no external
+* persistence, no cross-process visibility, and no durability guarantee —
+* it exists for development, tests, and examples, but honors the same
+* claim/record contract a durable store must honor.
+*/
+function memoryStore() {
+	const claims = /* @__PURE__ */ new Map();
+	return {
+		async claim(claim$1) {
+			const identity = identityKey(claim$1);
+			const existing = claims.get(identity);
+			if (existing !== void 0) {
+				if (existing.claim.inputFingerprint !== claim$1.inputFingerprint) return {
+					status: "conflict",
+					executionId: existing.executionId
+				};
+				return {
+					status: "existing",
+					outcome: existing.outcome
+				};
+			}
+			let settle$1;
+			const outcome = new Promise((resolve) => {
+				settle$1 = resolve;
+			});
+			const executionId = crypto.randomUUID();
+			claims.set(identity, {
+				claim: claim$1,
+				executionId,
+				outcome,
+				settle: settle$1,
+				settled: false
+			});
+			return {
+				status: "claimed",
+				executionId
+			};
+		},
+		async record(execution) {
+			const identity = identityKey(execution.evidence);
+			const entry = claims.get(identity);
+			if (entry === void 0 || entry.executionId !== execution.evidence.executionId) throw new Error(`record() called for unclaimed executionId "${execution.evidence.executionId}".`);
+			if (entry.settled) throw new Error(`record() called twice for executionId "${entry.executionId}".`);
+			entry.settled = true;
+			entry.settle(execution);
+		}
+	};
+}
+function identityKey(claim$1) {
+	return `${claim$1.capability}:${claim$1.principalId}:${claim$1.idempotencyKey}`;
+}
+
+//#endregion
+export { capability, createKaji, knownFailure, memoryStore };