@choiceapps/communityservices-sdk 0.1.0

package/dist/cjs/validation.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRecord = isRecord;
+exports.matches = matches;
+exports.decodeResponse = decodeResponse;
+const runtime_js_1 = require("./runtime.js");
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Validates the structural subset used by the pinned specifications. */
+function matches(value, schema, registry, mode, depth = 0) {
+    if (depth > 100)
+        return false;
+    if (value === null && schema.nullable)
+        return true;
+    if (schema.$ref) {
+        const target = registry[schema.$ref.split("/").at(-1) ?? ""];
+        return target !== undefined && matches(value, target, registry, mode, depth + 1);
+    }
+    if (schema.enum && !schema.enum.includes(value))
+        return false;
+    switch (schema.type?.toLowerCase()) {
+        case "string":
+            if (schema.format === "binary")
+                return value instanceof Blob;
+            if (typeof value !== "string")
+                return false;
+            // Format strings and .NET regexes are not portable business validation.
+            return mode === "response" || ((schema.minLength === undefined || value.length >= schema.minLength) && (schema.maxLength === undefined || value.length <= schema.maxLength));
+        case "integer": return typeof value === "number" && Number.isSafeInteger(value);
+        case "number": return typeof value === "number" && Number.isFinite(value);
+        case "boolean": return typeof value === "boolean";
+        case "array": {
+            const itemSchema = schema.items;
+            return Array.isArray(value) && itemSchema !== undefined && value.every(item => matches(item, itemSchema, registry, mode, depth + 1));
+        }
+        case "object": {
+            if (!isRecord(value))
+                return false;
+            if (schema.required?.some(key => !Object.hasOwn(value, key) || value[key] === undefined))
+                return false;
+            for (const [key, child] of Object.entries(schema.properties ?? {})) {
+                if (Object.hasOwn(value, key) && value[key] !== undefined && !matches(value[key], child, registry, mode, depth + 1))
+                    return false;
+            }
+            // Response fields added by WellSky are allowed. Request typos are rejected.
+            if (mode === "request" && schema.additionalProperties === false && Object.keys(value).some(key => !Object.hasOwn(schema.properties ?? {}, key)))
+                return false;
+            return true;
+        }
+        default: return false;
+    }
+}
+function decodeResponse(value, schema, registry, operation) {
+    // No schema means the public return type is unknown; empty responses remain null.
+    if (!schema || value === null)
+        return value;
+    let valid;
+    if (Array.isArray(value))
+        valid = value.every(item => matches(item, schema, registry, "response"));
+    else if (isRecord(value) && Object.hasOwn(value, "value")) {
+        valid = Array.isArray(value.value) && value.value.every(item => matches(item, schema, registry, "response")) &&
+            (value["@odata.count"] === undefined || typeof value["@odata.count"] === "number" && Number.isSafeInteger(value["@odata.count"]) && value["@odata.count"] >= 0) &&
+            (value["@odata.nextLink"] === undefined || typeof value["@odata.nextLink"] === "string");
+    }
+    else if (isRecord(value) && (Object.hasOwn(value, "count") || Object.hasOwn(value, "values"))) {
+        valid = typeof value.count === "number" && Number.isSafeInteger(value.count) && value.count >= 0 &&
+            Array.isArray(value.values) && value.values.every(item => matches(item, schema, registry, "response"));
+    }
+    else
+        valid = matches(value, schema, registry, "response");
+    if (!valid)
+        throw new runtime_js_1.WellSkyError("protocol", operation);
+    // Generated return types and runtime schemas come from the same specification.
+    return value;
+}
+//# sourceMappingURL=validation.js.map

package/dist/cjs/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/validation.ts"],"names":[],"mappings":"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","sourcesContent":["import { WellSkyError } from \"./runtime.js\";\n\nexport interface Schema {\n  $ref?: string;\n  type?: string;\n  format?: string;\n  nullable?: boolean;\n  properties?: Record<string, Schema>;\n  required?: string[];\n  items?: Schema;\n  additionalProperties?: boolean | Schema;\n  minLength?: number;\n  maxLength?: number;\n  pattern?: string;\n  default?: unknown;\n  enum?: unknown[];\n}\n\nexport type SchemaRegistry = Record<string, Schema>;\nexport type Method = \"GET\" | \"POST\" | \"PUT\" | \"DELETE\" | \"PATCH\" | \"HEAD\" | \"OPTIONS\";\nexport interface OperationDefinition {\n  method: Method;\n  path: string;\n  authenticated: boolean;\n  pathSchema: Schema;\n  querySchema: Schema;\n  bodySchema?: Schema;\n  responseSchema?: Schema;\n  multipart: boolean;\n  pageable: boolean;\n}\n\nexport function isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/** Validates the structural subset used by the pinned specifications. */\nexport function matches(value: unknown, schema: Schema, registry: SchemaRegistry, mode: \"request\" | \"response\", depth = 0): boolean {\n  if (depth > 100) return false;\n  if (value === null && schema.nullable) return true;\n  if (schema.$ref) {\n    const target = registry[schema.$ref.split(\"/\").at(-1) ?? \"\"];\n    return target !== undefined && matches(value, target, registry, mode, depth + 1);\n  }\n  if (schema.enum && !schema.enum.includes(value)) return false;\n  switch (schema.type?.toLowerCase()) {\n    case \"string\":\n      if (schema.format === \"binary\") return value instanceof Blob;\n      if (typeof value !== \"string\") return false;\n      // Format strings and .NET regexes are not portable business validation.\n      return mode === \"response\" || ((schema.minLength === undefined || value.length >= schema.minLength) && (schema.maxLength === undefined || value.length <= schema.maxLength));\n    case \"integer\": return typeof value === \"number\" && Number.isSafeInteger(value);\n    case \"number\": return typeof value === \"number\" && Number.isFinite(value);\n    case \"boolean\": return typeof value === \"boolean\";\n    case \"array\": {\n      const itemSchema = schema.items;\n      return Array.isArray(value) && itemSchema !== undefined && value.every(item => matches(item, itemSchema, registry, mode, depth + 1));\n    }\n    case \"object\": {\n      if (!isRecord(value)) return false;\n      if (schema.required?.some(key => !Object.hasOwn(value, key) || value[key] === undefined)) return false;\n      for (const [key, child] of Object.entries(schema.properties ?? {})) {\n        if (Object.hasOwn(value, key) && value[key] !== undefined && !matches(value[key], child, registry, mode, depth + 1)) return false;\n      }\n      // Response fields added by WellSky are allowed. Request typos are rejected.\n      if (mode === \"request\" && schema.additionalProperties === false && Object.keys(value).some(key => !Object.hasOwn(schema.properties ?? {}, key))) return false;\n      return true;\n    }\n    default: return false;\n  }\n}\n\nexport function decodeResponse<T>(value: unknown, schema: Schema | undefined, registry: SchemaRegistry, operation: string): T {\n  // No schema means the public return type is unknown; empty responses remain null.\n  if (!schema || value === null) return value as T;\n  let valid: boolean;\n  if (Array.isArray(value)) valid = value.every(item => matches(item, schema, registry, \"response\"));\n  else if (isRecord(value) && Object.hasOwn(value, \"value\")) {\n    valid = Array.isArray(value.value) && value.value.every(item => matches(item, schema, registry, \"response\")) &&\n      (value[\"@odata.count\"] === undefined || typeof value[\"@odata.count\"] === \"number\" && Number.isSafeInteger(value[\"@odata.count\"]) && value[\"@odata.count\"] >= 0) &&\n      (value[\"@odata.nextLink\"] === undefined || typeof value[\"@odata.nextLink\"] === \"string\");\n  } else if (isRecord(value) && (Object.hasOwn(value, \"count\") || Object.hasOwn(value, \"values\"))) {\n    valid = typeof value.count === \"number\" && Number.isSafeInteger(value.count) && value.count >= 0 &&\n      Array.isArray(value.values) && value.values.every(item => matches(item, schema, registry, \"response\"));\n  } else valid = matches(value, schema, registry, \"response\");\n  if (!valid) throw new WellSkyError(\"protocol\", operation);\n  // Generated return types and runtime schemas come from the same specification.\n  return value as T;\n}\n"]}

package/dist/cjs/verification.d.ts

@@ -0,0 +1,82 @@
+import { WellSkyError } from "./runtime.js";
+import type { RequestOptions } from "./runtime.js";
+export type ReadOutcome<T> = {
+    kind: "found";
+    value: T;
+} | {
+    kind: "absent";
+} | {
+    kind: "unknown";
+    error: WellSkyError;
+};
+export interface ReadBackEvidence {
+    endpoint: string;
+    readAt: string;
+    ids: Record<string, number>;
+    fields: Record<string, "match" | "absent" | "different">;
+}
+export interface FieldMismatch {
+    field: string;
+    expected: string;
+    actual: string | null;
+}
+export interface AttemptInfo {
+    correlationId: string;
+    startedAt: string;
+    durationMs: number;
+    httpStatus?: number;
+}
+interface AttemptResult {
+    requestHash: string;
+    attempt: AttemptInfo;
+}
+export type WriteResult<T> = (AttemptResult & {
+    status: "verified";
+    committed: true;
+    data: T;
+    evidence: ReadBackEvidence;
+}) | (AttemptResult & {
+    status: "unverified";
+    committed: true | "unknown";
+    data?: Partial<T>;
+    mismatches?: FieldMismatch[];
+    evidence?: ReadBackEvidence;
+    error?: WellSkyError;
+}) | (AttemptResult & {
+    status: "failed";
+    committed: false;
+    reason: "preflight" | "rejected" | "proven_absent";
+    error: WellSkyError;
+});
+/** Include tenant, target IDs, operation, effective date, and encoded answers in the input. */
+export declare function semanticHash(value: unknown, options?: RequestOptions): Promise<string>;
+/** Absence semantics are endpoint-specific. No HTTP status means absent by default. */
+export declare function readOutcome<T>(reader: () => Promise<T>, options: {
+    operation: string;
+    isAbsent?: (value: T) => boolean;
+    absentStatuses?: readonly number[];
+    signal?: AbortSignal;
+}): Promise<ReadOutcome<T>>;
+export interface ReadBackRecord<T> {
+    data: T;
+    ids: Record<string, number>;
+    fields: Record<string, unknown>;
+    /** Set only when the read proves this attempt committed, not just that an older record exists. */
+    commitConfirmed?: boolean;
+}
+export interface VerificationPlan<T> extends RequestOptions {
+    operation: string;
+    readEndpoint: string;
+    semanticPayload: unknown;
+    expectedFields: Record<string, unknown>;
+    preflight?: (options: RequestOptions) => Promise<void>;
+    submit: (options: RequestOptions) => Promise<unknown>;
+    readBack: (options: RequestOptions) => Promise<ReadOutcome<ReadBackRecord<T>>>;
+    /** An authoritative proof supplied by an endpoint adapter, not merely an empty list or a 404. */
+    proveNotCommitted?: (options: RequestOptions) => Promise<boolean>;
+    mode?: "write" | "verify-only";
+}
+/** Sends at most once, always reads back, and never infers success or rollback from an HTTP status. */
+export declare function verifyWrite<T>(plan: VerificationPlan<T>): Promise<WriteResult<T>>;
+export {};
+//# sourceMappingURL=verification.d.ts.map

package/dist/cjs/verification.d.ts.map

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

package/dist/cjs/verification.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.semanticHash = semanticHash;
+exports.readOutcome = readOutcome;
+exports.verifyWrite = verifyWrite;
+const runtime_js_1 = require("./runtime.js");
+const errors_js_1 = require("./errors.js");
+function canonical(value, seen = new Set()) {
+    if (value === null)
+        return "null";
+    if (typeof value === "string" || typeof value === "boolean")
+        return JSON.stringify(value);
+    if (typeof value === "number" && Number.isFinite(value))
+        return JSON.stringify(value);
+    if (typeof value !== "object" || seen.has(value))
+        throw new errors_js_1.ValidationError("semantic payload hash");
+    seen.add(value);
+    let result;
+    // Array.from visits holes as undefined, which canonical rejects. map skips them
+    // and would otherwise hash a one-hole array exactly like an empty array.
+    if (Array.isArray(value))
+        result = `[${Array.from(value, item => canonical(item, seen)).join(",")}]`;
+    else {
+        if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+            throw new errors_js_1.ValidationError("semantic payload hash");
+        result = `{${Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, item]) => `${JSON.stringify(key)}:${canonical(item, seen)}`).join(",")}}`;
+    }
+    seen.delete(value);
+    return result;
+}
+/** Include tenant, target IDs, operation, effective date, and encoded answers in the input. */
+async function semanticHash(value, options = {}) {
+    options.signal?.throwIfAborted();
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonical(value)));
+    options.signal?.throwIfAborted();
+    return Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, "0")).join("");
+}
+function safeError(error, operation) {
+    return error instanceof runtime_js_1.WellSkyError ? error : new runtime_js_1.WellSkyError("protocol", operation);
+}
+/** Absence semantics are endpoint-specific. No HTTP status means absent by default. */
+async function readOutcome(reader, options) {
+    try {
+        options.signal?.throwIfAborted();
+        const value = await reader();
+        return options.isAbsent?.(value) ? { kind: "absent" } : { kind: "found", value };
+    }
+    catch (error) {
+        const safe = safeError(error, options.operation);
+        if (safe.status !== undefined && options.absentStatuses?.includes(safe.status))
+            return { kind: "absent" };
+        return { kind: "unknown", error: safe };
+    }
+}
+/** Sends at most once, always reads back, and never infers success or rollback from an HTTP status. */
+async function verifyWrite(plan) {
+    const started = Date.now();
+    const correlationId = plan.correlationId ?? crypto.randomUUID();
+    const context = { correlationId, ...(plan.signal ? { signal: plan.signal } : {}), ...(plan.timeoutMs === undefined ? {} : { timeoutMs: plan.timeoutMs }) };
+    // Hashing invalid semantic input throws before any network operation.
+    const requestHash = await semanticHash(plan.semanticPayload);
+    let httpStatus;
+    const base = () => ({ requestHash, attempt: { correlationId, startedAt: new Date(started).toISOString(), durationMs: Date.now() - started, ...(httpStatus === undefined ? {} : { httpStatus }) } });
+    try {
+        plan.signal?.throwIfAborted();
+        await plan.preflight?.(context);
+        if (!Object.keys(plan.expectedFields).length)
+            throw new errors_js_1.ValidationError(plan.operation, ["expectedFields"]);
+        for (const value of Object.values(plan.expectedFields))
+            canonical(value);
+        plan.signal?.throwIfAborted();
+    }
+    catch (error) {
+        return { ...base(), status: "failed", committed: false, reason: "preflight", error: safeError(error, plan.operation) };
+    }
+    let writeError;
+    if (plan.mode !== "verify-only") {
+        try {
+            await plan.submit(context);
+        }
+        catch (error) {
+            writeError = safeError(error, plan.operation);
+            httpStatus = writeError.status;
+        }
+    }
+    let read;
+    try {
+        read = await plan.readBack(context);
+    }
+    catch (error) {
+        read = { kind: "unknown", error: safeError(error, plan.readEndpoint) };
+    }
+    if (read.kind === "unknown")
+        return { ...base(), status: "unverified", committed: "unknown", error: read.error };
+    if (read.kind === "absent") {
+        let proven = false;
+        try {
+            proven = await plan.proveNotCommitted?.(context) === true;
+        }
+        catch { /* An unavailable proof is not absence. */ }
+        const error = writeError ?? new errors_js_1.AmbiguousCommitError(plan.operation);
+        return proven ? { ...base(), status: "failed", committed: false, reason: writeError?.status && writeError.status >= 400 && writeError.status < 500 ? "rejected" : "proven_absent", error } : { ...base(), status: "unverified", committed: "unknown", error };
+    }
+    const fields = {};
+    const mismatches = [];
+    for (const [field, expected] of Object.entries(plan.expectedFields)) {
+        const present = Object.hasOwn(read.value.fields, field);
+        let equal = false;
+        try {
+            equal = present && canonical(expected) === canonical(read.value.fields[field]);
+        }
+        catch { /* Malformed read values cannot verify a write. */ }
+        fields[field] = equal ? "match" : present ? "different" : "absent";
+        if (!equal)
+            mismatches.push({ field, expected: "[REDACTED]", actual: present ? "[REDACTED]" : null });
+    }
+    const evidence = { endpoint: plan.readEndpoint, readAt: new Date().toISOString(), ids: { ...read.value.ids }, fields };
+    if (!mismatches.length)
+        return { ...base(), status: "verified", committed: true, data: read.value.data, evidence };
+    return { ...base(), status: "unverified", committed: read.value.commitConfirmed === true ? true : "unknown", data: read.value.data, mismatches, evidence, ...(writeError ? { error: writeError } : {}) };
+}
+//# sourceMappingURL=verification.js.map

package/dist/cjs/verification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification.js","sourceRoot":"","sources":["../../src/verification.ts"],"names":[],"mappings":"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","sourcesContent":["import { WellSkyError } from \"./runtime.js\";\nimport type { RequestOptions } from \"./runtime.js\";\nimport { AmbiguousCommitError, ValidationError } from \"./errors.js\";\n\nexport type ReadOutcome<T> = { kind: \"found\"; value: T } | { kind: \"absent\" } | { kind: \"unknown\"; error: WellSkyError };\nexport interface ReadBackEvidence {\n  endpoint: string;\n  readAt: string;\n  ids: Record<string, number>;\n  fields: Record<string, \"match\" | \"absent\" | \"different\">;\n}\nexport interface FieldMismatch { field: string; expected: string; actual: string | null }\nexport interface AttemptInfo { correlationId: string; startedAt: string; durationMs: number; httpStatus?: number }\ninterface AttemptResult { requestHash: string; attempt: AttemptInfo }\nexport type WriteResult<T> =\n  | (AttemptResult & { status: \"verified\"; committed: true; data: T; evidence: ReadBackEvidence })\n  | (AttemptResult & { status: \"unverified\"; committed: true | \"unknown\"; data?: Partial<T>; mismatches?: FieldMismatch[]; evidence?: ReadBackEvidence; error?: WellSkyError })\n  | (AttemptResult & { status: \"failed\"; committed: false; reason: \"preflight\" | \"rejected\" | \"proven_absent\"; error: WellSkyError });\n\nfunction canonical(value: unknown, seen = new Set<object>()): string {\n  if (value === null) return \"null\";\n  if (typeof value === \"string\" || typeof value === \"boolean\") return JSON.stringify(value);\n  if (typeof value === \"number\" && Number.isFinite(value)) return JSON.stringify(value);\n  if (typeof value !== \"object\" || seen.has(value)) throw new ValidationError(\"semantic payload hash\");\n  seen.add(value);\n  let result: string;\n  // Array.from visits holes as undefined, which canonical rejects. map skips them\n  // and would otherwise hash a one-hole array exactly like an empty array.\n  if (Array.isArray(value)) result = `[${Array.from(value, item => canonical(item, seen)).join(\",\")}]`;\n  else {\n    if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) throw new ValidationError(\"semantic payload hash\");\n    result = `{${Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, item]) => `${JSON.stringify(key)}:${canonical(item, seen)}`).join(\",\")}}`;\n  }\n  seen.delete(value);\n  return result;\n}\n\n/** Include tenant, target IDs, operation, effective date, and encoded answers in the input. */\nexport async function semanticHash(value: unknown, options: RequestOptions = {}): Promise<string> {\n  options.signal?.throwIfAborted();\n  const digest = await crypto.subtle.digest(\"SHA-256\", new TextEncoder().encode(canonical(value)));\n  options.signal?.throwIfAborted();\n  return Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, \"0\")).join(\"\");\n}\n\nfunction safeError(error: unknown, operation: string): WellSkyError {\n  return error instanceof WellSkyError ? error : new WellSkyError(\"protocol\", operation);\n}\n\n/** Absence semantics are endpoint-specific. No HTTP status means absent by default. */\nexport async function readOutcome<T>(reader: () => Promise<T>, options: { operation: string; isAbsent?: (value: T) => boolean; absentStatuses?: readonly number[]; signal?: AbortSignal }): Promise<ReadOutcome<T>> {\n  try {\n    options.signal?.throwIfAborted();\n    const value = await reader();\n    return options.isAbsent?.(value) ? { kind: \"absent\" } : { kind: \"found\", value };\n  } catch (error) {\n    const safe = safeError(error, options.operation);\n    if (safe.status !== undefined && options.absentStatuses?.includes(safe.status)) return { kind: \"absent\" };\n    return { kind: \"unknown\", error: safe };\n  }\n}\n\nexport interface ReadBackRecord<T> {\n  data: T;\n  ids: Record<string, number>;\n  fields: Record<string, unknown>;\n  /** Set only when the read proves this attempt committed, not just that an older record exists. */\n  commitConfirmed?: boolean;\n}\nexport interface VerificationPlan<T> extends RequestOptions {\n  operation: string;\n  readEndpoint: string;\n  semanticPayload: unknown;\n  expectedFields: Record<string, unknown>;\n  preflight?: (options: RequestOptions) => Promise<void>;\n  submit: (options: RequestOptions) => Promise<unknown>;\n  readBack: (options: RequestOptions) => Promise<ReadOutcome<ReadBackRecord<T>>>;\n  /** An authoritative proof supplied by an endpoint adapter, not merely an empty list or a 404. */\n  proveNotCommitted?: (options: RequestOptions) => Promise<boolean>;\n  mode?: \"write\" | \"verify-only\";\n}\n\n/** Sends at most once, always reads back, and never infers success or rollback from an HTTP status. */\nexport async function verifyWrite<T>(plan: VerificationPlan<T>): Promise<WriteResult<T>> {\n  const started = Date.now();\n  const correlationId = plan.correlationId ?? crypto.randomUUID();\n  const context: RequestOptions = { correlationId, ...(plan.signal ? { signal: plan.signal } : {}), ...(plan.timeoutMs === undefined ? {} : { timeoutMs: plan.timeoutMs }) };\n  // Hashing invalid semantic input throws before any network operation.\n  const requestHash = await semanticHash(plan.semanticPayload);\n  let httpStatus: number | undefined;\n  const base = (): AttemptResult => ({ requestHash, attempt: { correlationId, startedAt: new Date(started).toISOString(), durationMs: Date.now() - started, ...(httpStatus === undefined ? {} : { httpStatus }) } });\n  try {\n    plan.signal?.throwIfAborted();\n    await plan.preflight?.(context);\n    if (!Object.keys(plan.expectedFields).length) throw new ValidationError(plan.operation, [\"expectedFields\"]);\n    for (const value of Object.values(plan.expectedFields)) canonical(value);\n    plan.signal?.throwIfAborted();\n  } catch (error) { return { ...base(), status: \"failed\", committed: false, reason: \"preflight\", error: safeError(error, plan.operation) }; }\n  let writeError: WellSkyError | undefined;\n  if (plan.mode !== \"verify-only\") {\n    try { await plan.submit(context); }\n    catch (error) { writeError = safeError(error, plan.operation); httpStatus = writeError.status; }\n  }\n  let read: ReadOutcome<ReadBackRecord<T>>;\n  try { read = await plan.readBack(context); }\n  catch (error) { read = { kind: \"unknown\", error: safeError(error, plan.readEndpoint) }; }\n  if (read.kind === \"unknown\") return { ...base(), status: \"unverified\", committed: \"unknown\", error: read.error };\n  if (read.kind === \"absent\") {\n    let proven = false;\n    try { proven = await plan.proveNotCommitted?.(context) === true; } catch { /* An unavailable proof is not absence. */ }\n    const error = writeError ?? new AmbiguousCommitError(plan.operation);\n    return proven ? { ...base(), status: \"failed\", committed: false, reason: writeError?.status && writeError.status >= 400 && writeError.status < 500 ? \"rejected\" : \"proven_absent\", error } : { ...base(), status: \"unverified\", committed: \"unknown\", error };\n  }\n  const fields: ReadBackEvidence[\"fields\"] = {};\n  const mismatches: FieldMismatch[] = [];\n  for (const [field, expected] of Object.entries(plan.expectedFields)) {\n    const present = Object.hasOwn(read.value.fields, field);\n    let equal = false;\n    try { equal = present && canonical(expected) === canonical(read.value.fields[field]); } catch { /* Malformed read values cannot verify a write. */ }\n    fields[field] = equal ? \"match\" : present ? \"different\" : \"absent\";\n    if (!equal) mismatches.push({ field, expected: \"[REDACTED]\", actual: present ? \"[REDACTED]\" : null });\n  }\n  const evidence: ReadBackEvidence = { endpoint: plan.readEndpoint, readAt: new Date().toISOString(), ids: { ...read.value.ids }, fields };\n  if (!mismatches.length) return { ...base(), status: \"verified\", committed: true, data: read.value.data, evidence };\n  return { ...base(), status: \"unverified\", committed: read.value.commitConfirmed === true ? true : \"unknown\", data: read.value.data, mismatches, evidence, ...(writeError ? { error: writeError } : {}) };\n}\n"]}

package/dist/esm/bulk.d.ts

@@ -0,0 +1,33 @@
+import { WellSkyError } from "./runtime.js";
+export type BulkItemResult<T> = {
+    index: number;
+    outcome: "fulfilled";
+    value: T;
+} | {
+    index: number;
+    outcome: "rejected";
+    error: WellSkyError;
+} | {
+    index: number;
+    outcome: "skipped";
+    reason: "cancelled" | "callback_failed";
+};
+export interface BulkReport<T> {
+    results: BulkItemResult<T>[];
+    callbackErrors: {
+        index: number;
+        error: WellSkyError;
+    }[];
+}
+export interface BulkOptions<T> {
+    concurrency?: number;
+    signal?: AbortSignal;
+    /** Called as each item completes. Awaited before scheduling the next item on that worker. */
+    onResult?: (result: BulkItemResult<T>) => void | Promise<void>;
+}
+/** No item is retried here. A rejected write promise does not prove the write was rolled back. */
+export declare function mapBulk<I, O>(items: readonly I[], worker: (item: I, context: {
+    index: number;
+    signal?: AbortSignal;
+}) => Promise<O>, options?: BulkOptions<O>): Promise<BulkReport<O>>;
+//# sourceMappingURL=bulk.d.ts.map

package/dist/esm/bulk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulk.d.ts","sourceRoot":"","sources":["../../src/bulk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5C,MAAM,MAAM,cAAc,CAAC,CAAC,IACxB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACjD;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,GAC3D;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,iBAAiB,CAAA;CAAE,CAAC;AACnF,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7B,cAAc,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,YAAY,CAAA;KAAE,EAAE,CAAC;CAC1D;AACD,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChE;AAED,kGAAkG;AAClG,wBAAsB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,WAAW,CAAC,CAAC,CAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CA0BhM"}

package/dist/esm/bulk.js

@@ -0,0 +1,39 @@
+import { WellSkyError } from "./runtime.js";
+import { ValidationError } from "./errors.js";
+/** No item is retried here. A rejected write promise does not prove the write was rolled back. */
+export async function mapBulk(items, worker, options = {}) {
+    const concurrency = options.concurrency ?? 8;
+    if (!Number.isSafeInteger(concurrency) || concurrency < 1)
+        throw new ValidationError("bulk configuration", ["concurrency"]);
+    const results = [];
+    const callbackErrors = [];
+    let next = 0;
+    let callbackFailed = false;
+    const jobs = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+        while (next < items.length && !options.signal?.aborted && !callbackFailed) {
+            const index = next++;
+            // The index is reserved synchronously and is bounded by items.length.
+            const item = items[index];
+            let result;
+            try {
+                result = { index, outcome: "fulfilled", value: await worker(item, { index, ...(options.signal ? { signal: options.signal } : {}) }) };
+            }
+            catch (error) {
+                result = { index, outcome: "rejected", error: error instanceof WellSkyError ? error : new WellSkyError("protocol", "bulk item") };
+            }
+            results[index] = result;
+            try {
+                await options.onResult?.(result);
+            }
+            catch {
+                callbackFailed = true;
+                callbackErrors.push({ index, error: new WellSkyError("protocol", "bulk result callback") });
+            }
+        }
+    });
+    await Promise.all(jobs);
+    for (let index = next; index < items.length; index++)
+        results[index] = { index, outcome: "skipped", reason: callbackFailed ? "callback_failed" : "cancelled" };
+    return { results, callbackErrors };
+}
+//# sourceMappingURL=bulk.js.map

package/dist/esm/bulk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulk.js","sourceRoot":"","sources":["../../src/bulk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAiB9C,kGAAkG;AAClG,MAAM,CAAC,KAAK,UAAU,OAAO,CAAO,KAAmB,EAAE,MAAiF,EAAE,UAA0B,EAAE;IACtK,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,WAAW,CAAC,IAAI,WAAW,GAAG,CAAC;QAAE,MAAM,IAAI,eAAe,CAAC,oBAAoB,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC;IAC5H,MAAM,OAAO,GAAwB,EAAE,CAAC;IACxC,MAAM,cAAc,GAAoC,EAAE,CAAC;IAC3D,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,cAAc,GAAG,KAAK,CAAC;IAC3B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,IAAI,EAAE;QAClF,OAAO,IAAI,GAAG,KAAK,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC,cAAc,EAAE,CAAC;YAC1E,MAAM,KAAK,GAAG,IAAI,EAAE,CAAC;YACrB,sEAAsE;YACtE,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAM,CAAC;YAC/B,IAAI,MAAyB,CAAC;YAC9B,IAAI,CAAC;gBAAC,MAAM,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;YAAC,CAAC;YAC9I,OAAO,KAAK,EAAE,CAAC;gBAAC,MAAM,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,YAAY,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,UAAU,EAAE,WAAW,CAAC,EAAE,CAAC;YAAC,CAAC;YACpJ,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC;YACxB,IAAI,CAAC;gBAAC,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAC;YAAC,CAAC;YACzC,MAAM,CAAC;gBACL,cAAc,GAAG,IAAI,CAAC;gBACtB,cAAc,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,YAAY,CAAC,UAAU,EAAE,sBAAsB,CAAC,EAAE,CAAC,CAAC;YAC9F,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;IACH,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACxB,KAAK,IAAI,KAAK,GAAG,IAAI,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE;QAAE,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IAC/J,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;AACrC,CAAC","sourcesContent":["import { WellSkyError } from \"./runtime.js\";\nimport { ValidationError } from \"./errors.js\";\n\nexport type BulkItemResult<T> =\n  | { index: number; outcome: \"fulfilled\"; value: T }\n  | { index: number; outcome: \"rejected\"; error: WellSkyError }\n  | { index: number; outcome: \"skipped\"; reason: \"cancelled\" | \"callback_failed\" };\nexport interface BulkReport<T> {\n  results: BulkItemResult<T>[];\n  callbackErrors: { index: number; error: WellSkyError }[];\n}\nexport interface BulkOptions<T> {\n  concurrency?: number;\n  signal?: AbortSignal;\n  /** Called as each item completes. Awaited before scheduling the next item on that worker. */\n  onResult?: (result: BulkItemResult<T>) => void | Promise<void>;\n}\n\n/** No item is retried here. A rejected write promise does not prove the write was rolled back. */\nexport async function mapBulk<I, O>(items: readonly I[], worker: (item: I, context: { index: number; signal?: AbortSignal }) => Promise<O>, options: BulkOptions<O> = {}): Promise<BulkReport<O>> {\n  const concurrency = options.concurrency ?? 8;\n  if (!Number.isSafeInteger(concurrency) || concurrency < 1) throw new ValidationError(\"bulk configuration\", [\"concurrency\"]);\n  const results: BulkItemResult<O>[] = [];\n  const callbackErrors: BulkReport<O>[\"callbackErrors\"] = [];\n  let next = 0;\n  let callbackFailed = false;\n  const jobs = Array.from({ length: Math.min(concurrency, items.length) }, async () => {\n    while (next < items.length && !options.signal?.aborted && !callbackFailed) {\n      const index = next++;\n      // The index is reserved synchronously and is bounded by items.length.\n      const item = items[index] as I;\n      let result: BulkItemResult<O>;\n      try { result = { index, outcome: \"fulfilled\", value: await worker(item, { index, ...(options.signal ? { signal: options.signal } : {}) }) }; }\n      catch (error) { result = { index, outcome: \"rejected\", error: error instanceof WellSkyError ? error : new WellSkyError(\"protocol\", \"bulk item\") }; }\n      results[index] = result;\n      try { await options.onResult?.(result); }\n      catch {\n        callbackFailed = true;\n        callbackErrors.push({ index, error: new WellSkyError(\"protocol\", \"bulk result callback\") });\n      }\n    }\n  });\n  await Promise.all(jobs);\n  for (let index = next; index < items.length; index++) results[index] = { index, outcome: \"skipped\", reason: callbackFailed ? \"callback_failed\" : \"cancelled\" };\n  return { results, callbackErrors };\n}\n"]}

package/dist/esm/control.d.ts

@@ -0,0 +1,35 @@
+import type { ClientEvent, ClientHealth, ClientOptions } from "./runtime.js";
+export declare class Semaphore {
+    #private;
+    active: number;
+    constructor(capacity: number);
+    get queued(): number;
+    acquire(signal: AbortSignal, operation: string): Promise<() => void>;
+}
+export interface SharedAuthentication {
+    cached?: {
+        token: string;
+        expiresAt: number;
+    } | undefined;
+    inFlight?: Promise<string> | undefined;
+}
+export declare function identity(value: object): number;
+/** Credentials are hashed for cache identity and never exposed in keys or diagnostics. */
+export declare function sharedAuthentication(scope: string, auth: ClientOptions["auth"]): Promise<SharedAuthentication>;
+export declare const tokenMintQueue: Semaphore;
+export declare class RequestControl {
+    #private;
+    readonly semaphore: Semaphore;
+    tokenMintCount: number;
+    constructor(concurrency: number, settings: {
+        threshold: number;
+        windowMs: number;
+        durationMs: number;
+    });
+    check(operation: string): void;
+    failed(status: number): number | undefined;
+    health(): ClientHealth;
+}
+export declare function requestControl(scope: string, options: ClientOptions): RequestControl;
+export declare function emit(options: Pick<ClientOptions, "hooks" | "logger">, event: ClientEvent): void;
+//# sourceMappingURL=control.d.ts.map

package/dist/esm/control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../../src/control.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAI7E,qBAAa,SAAS;;IACpB,MAAM,SAAK;gBAGC,QAAQ,EAAE,MAAM;IAC5B,IAAI,MAAM,IAAI,MAAM,CAA+B;IACnD,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;CAuBrE;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAC1D,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;CACxC;AAGD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI9C;AAED,0FAA0F;AAC1F,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,oBAAoB,CAAC,CASpH;AACD,eAAO,MAAM,cAAc,WAAmB,CAAC;AAE/C,qBAAa,cAAc;;IACzB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAI9B,cAAc,SAAK;gBACP,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;IAItG,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI9B,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAQ1C,MAAM,IAAI,YAAY;CAGvB;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,cAAc,CASpF;AAED,wBAAgB,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,OAAO,GAAG,QAAQ,CAAC,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAO/F"}

package/dist/esm/control.js

@@ -0,0 +1,132 @@
+import { WellSkyError } from "./runtime.js";
+import { CooldownError } from "./errors.js";
+export class Semaphore {
+    active = 0;
+    #capacity;
+    #queue = [];
+    constructor(capacity) { this.#capacity = capacity; }
+    get queued() { return this.#queue.length; }
+    acquire(signal, operation) {
+        return new Promise((resolve, reject) => {
+            let released = false;
+            const grant = () => {
+                signal.removeEventListener("abort", abort);
+                this.active++;
+                resolve(() => {
+                    if (released)
+                        return;
+                    released = true;
+                    this.active--;
+                    this.#queue.shift()?.grant();
+                });
+            };
+            const abort = () => {
+                const index = this.#queue.indexOf(waiter);
+                if (index >= 0)
+                    this.#queue.splice(index, 1);
+                reject(new WellSkyError(signal.reason instanceof DOMException && signal.reason.name === "TimeoutError" ? "timeout" : "aborted", operation));
+            };
+            const waiter = { grant, signal, abort };
+            if (signal.aborted) {
+                abort();
+                return;
+            }
+            if (this.active < this.#capacity)
+                grant();
+            else {
+                this.#queue.push(waiter);
+                signal.addEventListener("abort", abort, { once: true });
+            }
+        });
+    }
+}
+const identities = new WeakMap();
+let nextIdentity = 1;
+export function identity(value) {
+    const prior = identities.get(value);
+    if (prior !== undefined)
+        return prior;
+    const id = nextIdentity++;
+    identities.set(value, id);
+    return id;
+}
+const authentication = new Map();
+/** Credentials are hashed for cache identity and never exposed in keys or diagnostics. */
+export async function sharedAuthentication(scope, auth) {
+    const descriptor = auth.kind === "credentials" ? [scope, auth.kind, auth.username, auth.password] : auth.kind === "provider" ? [scope, auth.kind, identity(auth.getToken)] : [scope, auth.kind];
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify(descriptor)));
+    const key = Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, "0")).join("");
+    const prior = authentication.get(key);
+    if (prior)
+        return prior;
+    const state = {};
+    authentication.set(key, state);
+    return state;
+}
+export const tokenMintQueue = new Semaphore(1);
+export class RequestControl {
+    semaphore;
+    #settings;
+    #failures = [];
+    #until = 0;
+    tokenMintCount = 0;
+    constructor(concurrency, settings) {
+        for (const value of [concurrency, settings.threshold, settings.windowMs, settings.durationMs])
+            if (!Number.isSafeInteger(value) || value < 1)
+                throw new TypeError("Concurrency and cooldown settings must be positive integers");
+        this.semaphore = new Semaphore(concurrency);
+        this.#settings = { ...settings };
+    }
+    check(operation) {
+        if (this.#until > Date.now())
+            throw new CooldownError(operation, this.#until);
+        if (this.#until !== 0) {
+            this.#until = 0;
+            this.#failures = [];
+        }
+    }
+    failed(status) {
+        if (status !== 401 && status !== 403 && status !== 429 && status < 500)
+            return undefined;
+        const now = Date.now();
+        this.#failures = this.#failures.filter(time => time > now - this.#settings.windowMs);
+        this.#failures.push(now);
+        if (this.#failures.length >= this.#settings.threshold && this.#until <= now) {
+            this.#until = now + this.#settings.durationMs;
+            return this.#until;
+        }
+        return undefined;
+    }
+    health() {
+        return { state: this.#until > Date.now() ? "open" : "closed", until: this.#until > Date.now() ? new Date(this.#until).toISOString() : null, activeRequests: this.semaphore.active, queuedRequests: this.semaphore.queued, tokenMintCount: this.tokenMintCount };
+    }
+}
+const controls = new Map();
+export function requestControl(scope, options) {
+    const concurrency = options.maxConcurrency ?? 8;
+    const cooldown = options.cooldown ?? { threshold: 5, windowMs: 10_000, durationMs: 30_000 };
+    const signature = JSON.stringify([concurrency, cooldown.threshold, cooldown.windowMs, cooldown.durationMs]);
+    const existing = controls.get(scope);
+    if (existing && existing.signature !== signature)
+        throw new TypeError("Clients sharing a tenant and transport must use the same concurrency/cooldown settings");
+    if (existing)
+        return existing.value;
+    const value = new RequestControl(concurrency, cooldown);
+    controls.set(scope, { signature, value });
+    return value;
+}
+export function emit(options, event) {
+    const hooks = options.hooks;
+    const handler = event.type === "request" ? hooks?.onRequest : event.type === "response" ? hooks?.onResponse : event.type === "tokenMint" ? hooks?.onTokenMint : event.type === "throttle" ? hooks?.onThrottle : hooks?.onCooldown;
+    const safe = Object.freeze({ ...event });
+    // Observers must not turn a completed write into a thrown error or a replay.
+    try {
+        void Promise.resolve(handler?.(safe)).catch(() => { });
+    }
+    catch { /* Observer failures cannot change request outcomes. */ }
+    try {
+        void Promise.resolve(options.logger?.(safe)).catch(() => { });
+    }
+    catch { /* Same boundary for user-supplied loggers. */ }
+}
+//# sourceMappingURL=control.js.map