@stigmer/server 3.14.0-dev.20260910084630

package/dist/domain/workflowinstance/steps.js

@@ -0,0 +1,143 @@
+/**
+ * WorkflowInstance domain pipeline steps — port the step half of
+ * pkg/domain/workflowinstance/controller: parent-workflow load through the
+ * in-process workflow client (the other direction of the mutual edge),
+ * the same-org business rule, the spec.workflow_id immutability guard
+ * (oss#646), and the default-instance visibility guard (oss#556). Proven by
+ * workflowinstance.conformance.test.ts (CONFORMANCE_TARGET=local) and
+ * the family test ../workflow/__tests__/workflow.test.ts (the mutual edge
+ * makes the two domains one testable unit).
+ */
+import { ConnectError } from "@connectrpc/connect";
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { isDefaultInstance } from "../../pipeline/apiresource-labels.js";
+import { failedPreconditionError, internalError, invalidArgumentError, notFoundError, } from "../../pipeline/errors.js";
+import { EXISTING_RESOURCE_KEY } from "../../pipeline/steps/load-existing.js";
+import { rejectDefaultInstanceVisibilityUpdate } from "../../pipeline/steps/validate-visibility.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
+/** Context key for the loaded parent workflow (Go ParentWorkflowKey). */
+export const PARENT_WORKFLOW_KEY = "parent_workflow";
+/**
+ * LoadParentWorkflow — create.go: loads the workflow the instance
+ * materializes and stashes it for the same-org rule. ANY load failure maps
+ * to NotFound("Workflow", id) — Go folds every client error into that arm
+ * (capital-W copy is the wire contract).
+ */
+export function newLoadParentWorkflowStep(loaderProvider, logger) {
+    return {
+        name: "LoadParentWorkflow",
+        async execute(ctx) {
+            const workflowId = ctx.input.spec?.workflowId ?? "";
+            logger.info("Loading parent workflow", { workflowId });
+            let parent;
+            try {
+                parent = await loaderProvider().get(workflowId);
+            }
+            catch (error) {
+                logger.warn("Parent workflow not found", {
+                    error: error instanceof ConnectError ? error.rawMessage : String(error),
+                    workflowId,
+                });
+                throw notFoundError("Workflow", workflowId);
+            }
+            ctx.set(PARENT_WORKFLOW_KEY, parent);
+        },
+    };
+}
+/**
+ * ValidateSameOrgBusinessRule — create.go: instances must live in the same
+ * organization as the parent workflow; cross-org instances could leak
+ * configuration/secrets. The message is the cross-edition wire contract.
+ */
+export function newValidateSameOrgBusinessRuleStep(logger) {
+    return {
+        name: "ValidateSameOrgBusinessRule",
+        execute(ctx) {
+            const parent = ctx.get(PARENT_WORKFLOW_KEY);
+            if (parent === undefined) {
+                throw new Error("parent workflow not found in context");
+            }
+            const targetOrg = ctx.newState.metadata?.org ?? "";
+            const workflowOrg = parent.metadata?.org ?? "";
+            if (workflowOrg !== targetOrg) {
+                logger.warn("Business rule violation: cannot create instance of workflow in different org", {
+                    workflowId: parent.metadata?.id ?? "",
+                    workflowOrg,
+                    instanceOrg: targetOrg,
+                });
+                throw invalidArgumentError("Cannot create instance of workflow in a different organization. " +
+                    `Workflow belongs to org '${workflowOrg}', instance target is org '${targetOrg}'.`);
+            }
+        },
+    };
+}
+/**
+ * ValidateInstanceUpdate — update.go: spec.workflow_id is immutable. An
+ * instance is a configured materialization OF one workflow — repointing it
+ * would silently change what its executions run while keeping the
+ * instance's identity, history, and references intact; create a new
+ * instance instead (oss#646).
+ *
+ * Rejecting (rather than silently preserving, as BuildUpdateState does for
+ * metadata.visibility) is deliberate: visibility has a legitimate second
+ * door — the guarded updateVisibility RPC — so stale manifests carrying an
+ * old level are routine and must not fail the update. The parent ref has
+ * NO other door; a differing value is always a client error and deserves a
+ * loud failure. Same posture as the AgentChannel/Schedule guards and the
+ * cloud edition's twin step. Runs after LoadExisting; Apply delegates to
+ * Update, so this guard covers the apply door too.
+ */
+export function newValidateInstanceUpdateStep() {
+    return {
+        name: "ValidateInstanceUpdate",
+        execute(ctx) {
+            const existing = ctx.get(EXISTING_RESOURCE_KEY);
+            if (existing === undefined) {
+                throw internalError(new Error("existing workflow instance not found in context"), "existing workflow instance not found in context");
+            }
+            if (ctx.input.spec?.workflowId !== existing.spec?.workflowId) {
+                throw failedPreconditionError(`spec.workflow_id is immutable (instance runs workflow ${existing.spec?.workflowId ?? ""}) — create a new instance to run a different workflow`);
+            }
+        },
+    };
+}
+/**
+ * RejectDefaultInstanceVisibilityUpdate — update_visibility.go: rejects
+ * visibility updates on a workflow's system-managed default instance — the
+ * workflow twin of the agentinstance guard (oss#556). Keyed on the
+ * reserved label OR the parent's authoritative status.default_instance_id
+ * pointer (covers pre-label legacy rows without a backfill migration; the
+ * pointer cannot be dropped by a client update the way the label can). A
+ * missing parent passes through; any other store failure is INTERNAL — a
+ * transient fault must not silently open the guard.
+ */
+export function newRejectDefaultWorkflowInstanceVisibilityUpdateStep(store, instanceKey) {
+    return {
+        name: "RejectDefaultInstanceVisibilityUpdate",
+        async execute(ctx) {
+            const instance = ctx.get(instanceKey);
+            if (isDefaultInstance(instance.metadata)) {
+                rejectDefaultInstanceVisibilityUpdate();
+            }
+            const parentId = instance.spec?.workflowId ?? "";
+            if (parentId === "") {
+                return;
+            }
+            let parent;
+            try {
+                parent = await store.getResource(ApiResourceKind.workflow, parentId, WorkflowSchema);
+            }
+            catch (error) {
+                if (error instanceof ResourceNotFoundError) {
+                    return;
+                }
+                throw internalError(error, "failed to load parent workflow for default-instance check");
+            }
+            if (parent.status?.defaultInstanceId === instance.metadata?.id) {
+                rejectDefaultInstanceVisibilityUpdate();
+            }
+        },
+    };
+}
+//# sourceMappingURL=steps.js.map

package/dist/domain/workflowinstance/steps.js.map

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

package/dist/encryption/codec.d.ts

@@ -0,0 +1,102 @@
+/**
+ * One version of the secret-value wire format (enc:v<N>:...) — ports the
+ * cloud edition's ai.stigmer.infra.encryption.SecretCodec: the whole
+ * mapping between the stored string and the plaintext, including where
+ * the bytes live, but NO policy.
+ *
+ * SecretService is the only caller: it owns every policy decision —
+ * idempotency short-circuits, unprefixed pass-through, which codec new
+ * writes use, unknown-version refusal — so a codec never sees a value
+ * that is already encrypted and never decides what "disabled" means.
+ * Registration flows through exactly one door: the built-in v1 codec is
+ * installed at the boot/compose.ts consumption site, extension codecs
+ * through the `secretCodecs` ExtensionDrivers field (never a module-level
+ * side registry — the DD-006 one-registry doctrine).
+ *
+ * In the Java original a codec was pure crypto over the stored string
+ * alone until v3; the v3 codec stores the secret's value in the vault KV
+ * store and keeps only an authenticated pointer in the string, so
+ * encrypt/decrypt there include store I/O (the vault project's DD-005
+ * widening). That is why every verb here is async even though the
+ * built-in v1 codec never awaits anything.
+ *
+ * TS shape note: Java's interface carries default methods; here the
+ * batch/lifecycle verbs are OPTIONAL and the facade owns the fallbacks
+ * (loop the singular verbs; delete is a no-op) — a codec implements them
+ * only when it can do better (the v2 envelope codec batches all data-key
+ * wraps into one Transit round trip).
+ */
+import type { EncryptionScope } from "./scope.js";
+export interface SecretCodec {
+    /**
+     * The version token this codec serves — the literal text between
+     * `enc:` and the second colon (e.g. "v1"). Dispatch compares tokens
+     * literally: "v01" is not "v1" and resolves to no codec, by design.
+     */
+    readonly version: string;
+    /**
+     * Encrypts a plaintext value, producing `enc:<version>:...`.
+     *
+     * @param plaintext never already encrypted (the facade short-circuits)
+     * @param scope the tenancy scope whose key seals this value; the v1
+     *   codec ignores it, vault-backed codecs key (and, when located,
+     *   place) the value by it
+     * @throws EncryptionUnavailableError when the codec's key provider
+     *   cannot be reached
+     */
+    encrypt(plaintext: string, scope: EncryptionScope): Promise<string>;
+    /**
+     * Decrypts a value carrying this codec's prefix. No scope parameter:
+     * the sealed value self-describes (the envelope carries its tenant and,
+     * for v3, its KV pointer).
+     *
+     * @throws InvalidCiphertextError when the value itself is bad
+     *   (tampered, truncated, malformed, wrong key)
+     * @throws EncryptionUnavailableError when the machinery to decrypt an
+     *   otherwise-plausible value is missing
+     */
+    decrypt(encrypted: string): Promise<string>;
+    /**
+     * Encrypts many values under one scope, key names from the map keys.
+     * OPTIONAL — absent, the facade loops encrypt(), which is correct for
+     * any codec; the v2 envelope codec implements it to wrap all data keys
+     * in ONE KEK round trip. Fails as a whole: callers of the batched
+     * paths fail the whole request on any encryption error, so per-entry
+     * partial results would go unused. Result keyed as the input,
+     * iteration order preserved.
+     */
+    encryptAll?(plaintexts: ReadonlyMap<string, string>, scope: EncryptionScope): Promise<Map<string, string>>;
+    /**
+     * Decrypts many values carrying this codec's prefix. OPTIONAL — same
+     * fallback and whole-batch failure contract as encryptAll; the v2
+     * envelope codec implements it to unwrap all data keys in one KEK
+     * round trip per key id.
+     */
+    decryptAll?(encrypted: ReadonlyMap<string, string>): Promise<Map<string, string>>;
+    /**
+     * Destroys any external state backing a stored value — the lifecycle
+     * hook v3 introduced (a resource deletion or secret-key removal must
+     * remove the value from the KV store, or it leaks there forever).
+     * OPTIONAL — absent means no-op, which is CORRECT for v1/v2: their
+     * stored string IS the (encrypted) value, so deleting the resource row
+     * deletes everything. Idempotent by contract. Call sites are delete
+     * paths whose database write already succeeded, so the facade's
+     * callers treat failures as best-effort (Stage 3 wires them).
+     *
+     * @throws InvalidCiphertextError when the value is bad (nothing
+     *   derivable to clean up)
+     * @throws EncryptionUnavailableError when the external state is
+     *   unreachable
+     */
+    delete?(encrypted: string): Promise<void>;
+    /**
+     * Whether this codec can actually seal new values. OPTIONAL — absent
+     * means enabled (the Java posture: a codec bean exists exactly when its
+     * key machinery does, so registration IS the ability to encrypt). Only
+     * the OSS v1 codec implements it: its keyless WARN-degrade state
+     * (oss#394) is a deliberate, modeled condition the write steps branch
+     * on.
+     */
+    isEnabled?(): boolean;
+}
+//# sourceMappingURL=codec.d.ts.map

package/dist/encryption/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/encryption/codec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;;;;;;;OASG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEpE;;;;;;;;;OASG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5C;;;;;;;;OAQG;IACH,UAAU,CAAC,CACT,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACvC,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAEhC;;;;;OAKG;IACH,UAAU,CAAC,CACT,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GACrC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAEhC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C;;;;;;;OAOG;IACH,SAAS,CAAC,IAAI,OAAO,CAAC;CACvB"}

package/dist/encryption/codec.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=codec.js.map

package/dist/encryption/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../src/encryption/codec.ts"],"names":[],"mappings":""}

package/dist/encryption/encryption.d.ts

@@ -0,0 +1,210 @@
+import type { SecretCodec } from "./codec.js";
+import type { EncryptionScope } from "./scope.js";
+import type { KeyLoaderOptions } from "./key-manager.js";
+export { DecryptionFailedError, EncryptionDisabledError, EncryptionUnavailableError, InvalidCiphertextError, } from "./errors.js";
+export { ENCRYPTED_PREFIX, GCM_NONCE_SIZE, GCM_TAG_SIZE, StaticKeySecretCodec, } from "./v1-codec.js";
+export { EncryptionScope, PLATFORM_TENANT } from "./scope.js";
+export type { SecretCodec } from "./codec.js";
+/** Env var configuring the secrets key (Base64 32B) — Go EnvKeyName. */
+export declare const ENCRYPTION_KEY_ENV_VAR = "STIGMER_ENCRYPTION_KEY";
+/** Key file under ~/.stigmer — Go KeyFileName. */
+export declare const ENCRYPTION_KEY_FILE_NAME = "encryption.key";
+/**
+ * Env var selecting the write codec — byte-pinned across editions (the
+ * cloud's stigmer.encryption.write-version binds the same name). OSS
+ * default: v1. A blank value normalizes to the default: this is a
+ * rollback lever, and rollback levers must be robust to sloppy unsetting
+ * (the Java EncryptionConfig note).
+ */
+export declare const ENCRYPTION_WRITE_VERSION_ENV_VAR = "STIGMER_ENCRYPTION_WRITE_VERSION";
+/** The OSS default write version — the built-in static-key codec. */
+export declare const DEFAULT_WRITE_VERSION = "v1";
+/**
+ * The sentinel replacing every non-empty secret value at every
+ * resource-returning boundary — Go steps.RedactedMarker, pinned by the
+ * conformance suite and byte-identical in the cloud edition. Lives with
+ * the facade (the Java shape) because reencrypt must refuse it;
+ * domain/environment/constants.ts re-exports it for its historical
+ * importers. A client sending it BACK on a write means "keep the existing
+ * secret" (the round-trip contract; see preserveRedactedSecrets).
+ */
+export declare const REDACTED_MARKER = "***REDACTED***";
+/**
+ * Go IsCiphertextShaped: whether a value merely has the SHAPE of
+ * ciphertext — the enc:v<N>: prefix — regardless of whether it is genuine.
+ *
+ * This is the request-boundary provenance test (oss#395, the Go twin of
+ * cloud#229): the prefix is a server-reserved sentinel, so client-supplied
+ * values matching it must be rejected with INVALID_ARGUMENT before they
+ * reach encrypt(), whose idempotent pass-through would otherwise persist
+ * them verbatim (letting a client store forged ciphertext that
+ * getSecretValue later decrypts with the deployment key). Module-level,
+ * like the redaction-marker constant, so boundary steps need no service
+ * instance and the rejection stays unconditional on keyless deployments.
+ */
+export declare function isCiphertextShaped(value: string): boolean;
+/**
+ * Encryption/decryption for environment (and other domain) secrets. Safe
+ * for concurrent use; construct via one of the factories below.
+ */
+export declare class SecretService {
+    private readonly codecs;
+    private readonly writeCodec;
+    /** Numeric form of the write version, for reencrypt's upward-only rule. */
+    private readonly writeVersionNumber;
+    private constructor();
+    /**
+     * Go NewSecretService, kept signature-stable across the codec seam: a
+     * v1-only facade writing v1 — the shape of every OSS deployment with no
+     * extension composed, and of every test that constructs the service
+     * directly. nil/empty key → disabled (pass-through) v1; a present key
+     * must be exactly 32 bytes.
+     */
+    static create(key: Buffer | undefined): SecretService;
+    /**
+     * Go NewSecretServiceFromEnv: a v1-only facade with the key from the
+     * shared ladder (env var → key file → auto-generate). Throws only on
+     * unusable explicit configuration; the composition root maps that to
+     * the WARN-degrade posture.
+     */
+    static fromEnv(options?: KeyLoaderOptions): SecretService;
+    /**
+     * The parameterized construction path — the composition root's door
+     * (boot/compose.ts assembles built-in v1 + extension codecs and the
+     * resolved write version). Fail-fast on a write version with no codec:
+     * refusing to start beats silently writing a different version (the
+     * Java @PostConstruct contract). Every map key must be a dispatchable
+     * v<digits> token matching its codec's own version — a registration
+     * dispatch could never reach must fail loudly, not sit dark.
+     */
+    static withCodecs(options: {
+        readonly codecs: ReadonlyMap<string, SecretCodec>;
+        readonly writeVersion: string;
+    }): SecretService;
+    /**
+     * Whether new values can actually be sealed — delegated to the write
+     * codec (absent isEnabled means enabled: registration IS the ability,
+     * the Java posture; only the OSS v1 codec models a keyless state). The
+     * write steps branch on this for the WARN-degrade posture (oss#394).
+     */
+    isEnabled(): boolean;
+    /**
+     * Go IsEncrypted — dispatch on STORED values (decrypt, preserve,
+     * re-encrypt). For CLIENT-SUPPLIED input at a request boundary use the
+     * module-level isCiphertextShaped — same test, different intent.
+     */
+    isEncrypted(value: string): boolean;
+    /**
+     * The version number a stored value carries (enc:v<N>: → N), or
+     * undefined for anything else (plaintext, markers, empty strings). The
+     * public face of the dispatch parse, for callers that classify stored
+     * values — the convergence sweep's upward-only rule and the
+     * encryption-state gauges key on it.
+     */
+    versionOf(value: string): number | undefined;
+    /**
+     * Encrypts a plaintext secret under the given scope, using the
+     * configured write version.
+     *
+     * Idempotent for already-prefixed input of ANY version — returned
+     * unchanged (no silent upgrades; see the module header). The
+     * pass-through TRUSTS its callers: it exists for store-restored
+     * ciphertext (the ***REDACTED*** round-trip), and it is NOT a safe
+     * place to validate provenance — only the request pipeline knows
+     * whether a prefixed value came from the store or from a client.
+     * Client-supplied enc:v<N>: input is rejected at every write boundary
+     * via isCiphertextShaped (oss#395); do not "fix" smuggling here.
+     */
+    encrypt(plaintext: string, scope: EncryptionScope): Promise<string>;
+    /**
+     * Encrypts many values under one scope in as few key-provider round
+     * trips as the write codec allows (one, for the v2 envelope codec).
+     * Per-entry semantics are identical to encrypt(): already-encrypted
+     * values of any version pass through unchanged. Result keyed as the
+     * input, iteration order preserved; fails as a whole (the batched
+     * write paths fail the whole request on any encryption error).
+     */
+    encryptAll(plaintexts: ReadonlyMap<string, string>, scope: EncryptionScope): Promise<Map<string, string>>;
+    /**
+     * Encrypts a batch capped at the v2 envelope format: the write codec
+     * when the write version is v1 or v2, the v2 codec when the write
+     * version is above it. The generalization of the Java facade's
+     * encryptAllV2 pin (vault project DD-005) for a family that includes
+     * v1-only OSS deployments — see the executioncontext rationale:
+     * ephemeral values on a latency-budgeted read path, sealed where v2
+     * costs one batched Transit round trip and v3 (no KV batch endpoint,
+     * located-scope requirement) cannot follow. At write=v1 this is the
+     * write codec (OSS today); at write=v2 it equals Java's pin; at a
+     * future write=v3 flip it keeps these lanes on v2 instead of breaking
+     * them.
+     */
+    encryptAllAtMostV2(plaintexts: ReadonlyMap<string, string>, scope: EncryptionScope): Promise<Map<string, string>>;
+    /**
+     * Decrypts an encrypted secret value, dispatching on the value's own
+     * version token. Unprefixed values pass through unchanged (legacy
+     * plaintext compatibility, pre-oss#405 rows); prefixed values decrypt
+     * or fail with the two-armed taxonomy (errors.ts). A version with no
+     * codec here is EncryptionUnavailableError — before the codec seam
+     * this build failed such values CLOSED as invalid base64 (the literal
+     * v1 prefix never stripped); the refusal stays closed, now with the
+     * honest arm and copy (a deliberate, recorded change — no wire test
+     * observes it).
+     */
+    decrypt(encrypted: string): Promise<string>;
+    /**
+     * Decrypts many values in as few key-provider round trips as their
+     * codecs allow, grouping by each value's own version token. Per-entry
+     * semantics are identical to decrypt(): non-encrypted values pass
+     * through. Fails as a whole — callers needing per-key skip semantics
+     * (the resolution lanes) loop decrypt() instead.
+     */
+    decryptAll(encrypted: ReadonlyMap<string, string>): Promise<Map<string, string>>;
+    /**
+     * Destroys any external state backing a stored value, dispatching on
+     * the value's own version token — the lifecycle counterpart of
+     * decrypt(). Plaintext and marker values are no-ops by construction;
+     * v1/v2 values are no-ops by codec contract (their stored string IS
+     * the value). Call sites are resource-delete and key-removal paths
+     * whose database write already succeeded, so callers treat failures as
+     * best-effort (the Stage 3 wiring owns that posture).
+     */
+    delete(storedValue: string): Promise<void>;
+    /**
+     * Re-encrypts a stored value to the current write version — the ONE
+     * deliberate exception to the no-silent-upgrades doctrine, built for
+     * the secret-convergence sweep and the future v3 migration pass. Three
+     * rules, each load-bearing (the Java facade's, verbatim):
+     *
+     *   - UPWARD-ONLY: a value already at (or above) the write version is
+     *     returned unchanged. Rolling the write-version lever down must
+     *     never trigger a mass downgrade — in a v3 world that would mean
+     *     mass KV destruction on a config change.
+     *   - ROUND-TRIP-VERIFIED: the new ciphertext is decrypted and compared
+     *     to the plaintext before being returned, so a codec bug can never
+     *     hand the caller an unreadable value to persist.
+     *   - NO EXTERNAL-STATE DESTRUCTION: an old value's backing state (v3
+     *     KV entries) is NOT destroyed here — the caller persists the new
+     *     value first and only then cleans up, or a failed persist would
+     *     leave the stored pointer dangling.
+     *
+     * A non-encrypted, non-marker value is treated as plaintext and sealed
+     * — stored plaintext secrets are damage from the fail-open era (the
+     * cloud's #226 lesson; OSS keyless windows leave the same rows) and
+     * sealing them is strictly an improvement. The literal redaction
+     * marker is refused as InvalidCiphertextError: a stored marker is
+     * corruption from a marker-persist bug, and sealing it would hide the
+     * corruption behind valid ciphertext.
+     *
+     * @throws InvalidCiphertextError value-scoped (callers may skip)
+     * @throws EncryptionUnavailableError infrastructure (callers must abort)
+     */
+    reencrypt(storedValue: string, scope: EncryptionScope): Promise<string>;
+    /** The batch-encrypt mechanics shared by encryptAll and the v2 cap. */
+    private encryptAllWith;
+    /**
+     * The codec for a stored value's version token, or the loud unavailable
+     * refusal — the Java registry's "no codec for this version" contract.
+     */
+    private codecFor;
+}
+//# sourceMappingURL=encryption.d.ts.map

package/dist/encryption/encryption.d.ts.map

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