@ionite/core 0.0.23-beta.20260812.6 → 0.0.23-beta.20260820.2

package/dist/index.d.ts

@@ -389,8 +389,8 @@ type AuthenticatedUser = WorkforceUser | Customer;
 * flows that are inherently human.
 */
 type AuthenticatedPrincipal = AuthenticatedUser | WorkloadPrincipal;
+import { StandardSchemaV1 as StandardSchemaV19 } from "@standard-schema/spec";
 import { StandardSchemaV1 as StandardSchemaV18 } from "@standard-schema/spec";
-import { StandardSchemaV1 as StandardSchemaV17 } from "@standard-schema/spec";
 /**
 * Third-party CIAM provider presets and claim mapping.
 *
@@ -504,12 +504,11 @@ declare const warnLogger: Logger;
 /** Synchronous, in-memory read surface for one code catalog entity kind. */
 type CodeCatalogNamespace<TEntity> = {
 	get(id: string): TEntity | undefined;
-	getByExternalId(externalId: string): TEntity | undefined;
 	list(): readonly TEntity[];
 };
 /**
 * Normalized, frozen code-declared catalog produced by {@link defineCatalog}. All entities are
-* deep-frozen, id-indexed, and carry `externalId` (defaulted to `id`).
+* deep-frozen and id-indexed.
 */
 type CodeCatalog = {
 	groups: CodeCatalogNamespace<Group>;
@@ -526,6 +525,7 @@ type CodeCatalogInput = {
 declare function isCodeCatalog(value: CodeCatalog | CodeCatalogInput): value is CodeCatalog;
 /** Normalize an `authz.catalog` config value: pass through a {@link CodeCatalog}, build one from input. */
 declare function toCodeCatalog(value: CodeCatalog | CodeCatalogInput): CodeCatalog;
+type CatalogEntityKind = "group" | "role" | "permission";
 /**
 * Build a validated, frozen {@link CodeCatalog} from declarative arrays. Call it once at module
 * scope in a pure authz module (no store imports) and wire the result via
@@ -533,33 +533,52 @@ declare function toCodeCatalog(value: CodeCatalog | CodeCatalogInput): CodeCatal
 *
 * Validation (throws {@link Error} at module evaluation on the first violation):
 * - ids are globally unique across groups, roles, AND permissions (one SCIM Groups id space);
-* - `externalId`s (after defaulting to `id`) are globally unique (SCIM `externalId eq` contract);
 * - every group -> group/role/permission reference (string id or embedded object) resolves to an
 *   entity declared in the catalog arrays, and every role -> permission reference likewise
 *   (`resources` refs are NOT validated here — resources live in the app's `ResourceProvider`);
 * - nested group composition is acyclic;
 * - `recommendedSubjectTypes` is a subset of `assignableSubjectTypes`.
 *
-* Side effects: entities missing `externalId` are stamped with `externalId = id`, then every
-* entity (and its arrays/metadata) is frozen.
+* Side effects: every entity (and its arrays/metadata) is frozen.
 */
 declare function defineCatalog(input: CodeCatalogInput): CodeCatalog;
+/** Resolve one code entity and its kind from the shared id space. */
+declare function getCodeCatalogEntity(code: CodeCatalog | undefined, id: string): {
+	entity: Group | Role | Permission;
+	kind: CatalogEntityKind;
+} | undefined;
+/** Return the entity namespace for one catalog kind. */
+declare function catalogEntityStore<TEntity extends Group | Role | Permission>(catalog: AccessCatalogStore, kind: CatalogEntityKind): EntityStore<TEntity>;
+/**
+* Merge a materialized row with its code template. The row owns presentation, receipts, lifecycle,
+* and other runtime metadata; code owns ids, subject scoping, and graph/resource structure.
+*/
+declare function mergeCodeCatalogEntity<TEntity extends Group | Role | Permission>(kind: CatalogEntityKind, code: TEntity, stored: TEntity): TEntity;
 /**
-* {@link AccessCatalogStore}-shaped READ union over the code-declared catalog and the optional
-* backing store (lookup order code -> store, per kind). This is the single surface SCIM Groups
-* reads and OAA projection enumerate so code entities are first-class entitlements to IAM tooling
-* without ever being stored. Returns undefined when neither source is wired.
+* Insert a code template into the runtime catalog only when no row exists. Existing rows are never
+* rewritten, preserving IAM-renamed presentation and receipts. `insertIfAbsent` closes the race
+* between the initial read and insert.
+*/
+declare function materializeCodeCatalogEntity<TEntity extends Group | Role | Permission>(kind: CatalogEntityKind, code: TEntity, store: EntityStore<TEntity>): Promise<TEntity>;
+/**
+* Mark materialized code rows as deprecated when their template no longer exists. Callers choose
+* when to run this lifecycle sweep; it never runs during config apply.
+*/
+declare function deprecateRetiredCodeCatalogRows(code: CodeCatalog | undefined, store: AccessCatalogStore, onlyId?: string): Promise<void>;
+/**
+* {@link AccessCatalogStore}-shaped read union over code templates and the runtime store. Store rows
+* win presentation for code ids, code owns their structure, and unmaterialized code entities remain
+* visible. Returns undefined when neither source is wired.
 */
 declare function unionCatalogRead(code: CodeCatalog | undefined, store: AccessCatalogStore | undefined): AccessCatalogStore | undefined;
 import { StandardSchemaV1 as StandardSchemaV15 } from "@standard-schema/spec";
 /**
-* IAM delta egress mode (RemoteConfig/ECI intent). Selects how access changes that occur inside the
-* application are surfaced to the enterprise's IAM/governance layer:
+* IAM delta egress mode (RemoteConfig/ECI intent). Selects how IAM-visible runtime changes that
+* occur inside the application are surfaced to the enterprise's IAM/governance layer:
 *
-* - `'patch'`: outbound SCIM into the IAM tool (per-resource PATCH/POST, externalId-only). The IAM
-*   tool's view stays fresh as access changes in the app, and the tool can reconcile the echo
-*   against the originating request (an unmatched change is an out-of-band access grant for the
-*   enterprise's policy to handle). See the README "IAM delta egress" section.
+* - `'patch'`: outbound SCIM into the IAM tool (per-resource POST/PUT/PATCH/DELETE,
+*   correlated by the App-owned id carried as SCIM `externalId`). The IAM tool's view stays fresh as users, materialized entitlement
+*   definitions, and access change in the app. See the README "IAM delta egress" section.
 *
 * Origin/trust: every push is authenticated with the app's outgoing workload client (OAuth bearer);
 * the receiver treats the authenticated workload identity as the verified origin. Audit
@@ -570,55 +589,65 @@ import { StandardSchemaV1 as StandardSchemaV15 } from "@standard-schema/spec";
 type IamDeltaMode = "patch";
 /** SCIM resource types the delta patch adapter addresses. */
 type IamDeltaResourceType = "user" | "group";
+/** Destination-owned reference captured from a SCIM User/Group response. */
+type DestinationReference = {
+	/** Service-provider-assigned SCIM resource id. */
+	providerId: string;
+	/** IAM-owned deep link where access to an entitlement can be requested, when supplied. */
+	requestUrl?: string;
+};
 /**
-* Cache key for an externalId -> destination provider id mapping. Scoped by `destination` (the SCIM
-* base URL) so the same `externalId` can map to different provider ids across IAM tools, and by
-* `tenantId` for multi-tenant isolation.
+* Full IAM delta snapshot supplied by the app's maintenance/reconcile path. It mirrors the entities
+* visible through IAM aggregation: users, durable entitlement definitions, and active access roots.
 */
-type IamDeltaIdMapKey = {
-	tenantId?: string;
-	/** Destination SCIM base URL (keys the mapping per IAM target). */
-	destination: string;
-	resourceType: IamDeltaResourceType;
-	externalId: string;
-};
-/**
-* Durable cache of `externalId -> destination provider id` so the patch adapter resolves a resource
-* once and reuses the id for subsequent writes (steady state = one write call, no lookup). The cache
-* is self-healing: a stale id (destination 404/410) is re-resolved via an externalId filter and the
-* mapping refreshed. The SDK NEVER resolves a destination resource by any attribute other than
-* `externalId`.
-*/
-interface IamDeltaIdMapStore {
-	get(key: IamDeltaIdMapKey): Promise<string | undefined>;
-	set(key: IamDeltaIdMapKey, providerId: string): Promise<void>;
-	delete(key: IamDeltaIdMapKey): Promise<void>;
-}
-/** Result of an app-driven full reconcile (re-push of all active roots). */
+type IamDeltaReconcileInput = {
+	users?: Iterable<BaseUser> | AsyncIterable<BaseUser>;
+	groups?: Iterable<Group> | AsyncIterable<Group>;
+	roles?: Iterable<Role> | AsyncIterable<Role>;
+	permissions?: Iterable<Permission> | AsyncIterable<Permission>;
+	access?: Iterable<AccessChange> | AsyncIterable<AccessChange>;
+};
+/** Result of an app-driven full reconcile (re-push of definitions, users, and active roots). */
 type IamDeltaReconcileResult = {
 	pushed: number;
 	skipped: number;
 	errors: string[];
 };
 /**
-* Projects access-root changes to the configured IAM delta destination. Implemented by the server
-* package; threaded into the access-mutation chokepoint so every grant/revoke that flows through the
-* SDK (including direct SCIM calls) is surfaced. `onGrant`/`onRevoke` resolve when the projection
-* completes (or resolve immediately when not ready). They are best-effort egress: the SCIM mutation
-* path awaits them (bounded) inside the request so no work is left detached (serverless-safe), but a
-* rejection is caught and reported as degraded egress — it never turns a committed store mutation
-* into a SCIM error. A rejected promise signals the projection failed so the caller can report it.
+* Projects observed runtime mutations to the configured IAM delta destination. The invariant is:
+* every runtime mutation the SDK observes that would change what IAM full sync shows must also
+* egress through this handle. That includes users, materialized entitlement definitions, and access
+* roots. Code templates are not pushed during config apply.
+*
+* Request-triggered methods resolve when projection completes (or immediately when not ready). They
+* are best-effort egress: the SCIM mutation path awaits them inside the request, but a rejection is
+* caught and reported as degraded egress — it never turns a committed store mutation into a SCIM
+* error. Reactive catalog/resource events use the same methods outside a request and warn on failure.
 *
 * Readiness follows the shared contract: `isReady()` is a synchronous check; `ready(timeout?)`
 * resolves once the emitter first becomes usable.
 */
 interface IamDeltaEmitter {
+	/** Upsert a full SCIM User representation at the destination. */
+	onUserUpsert(user: BaseUser): Promise<void>;
+	/** Delete a destination User identified strictly by externalId. */
+	onUserDelete(externalId: string): Promise<void>;
+	/** Upsert a full SCIM Group representation for a group, role, or permission definition. */
+	onEntitlementUpsert(entity: Entitlement, type: EntitlementType): Promise<void>;
+	/** Delete a destination entitlement Group identified by the App-owned catalog id. */
+	onEntitlementDelete(type: EntitlementType, id: string): Promise<void>;
 	/** Project a granted root; resolves on completion (or immediately when not ready), rejects on push failure. */
 	onGrant(change: AccessChange): Promise<void>;
 	/** Project a revoked root; resolves on completion (or immediately when not ready), rejects on push failure. */
 	onRevoke(change: AccessChange): Promise<void>;
-	/** Re-push all active roots to the destination (app-driven full reconcile). */
-	reconcile(roots: AsyncIterable<AccessChange> | Iterable<AccessChange>): Promise<IamDeltaReconcileResult>;
+	/** Re-push the complete IAM-visible snapshot to the destination (app-driven full reconcile). */
+	reconcile(input: IamDeltaReconcileInput): Promise<IamDeltaReconcileResult>;
+	/**
+	* Read a previously captured destination reference without making a network request. Returns
+	* undefined until the resource has been resolved or pushed to the configured IAM destination.
+	* `correlationId` is a User's `externalId` or an entitlement's App-owned catalog `id`.
+	*/
+	getDestinationRef(resourceType: IamDeltaResourceType, correlationId: string): Promise<DestinationReference | undefined>;
 	isReady(): boolean;
 	ready(timeout?: number): Promise<void>;
 }
@@ -1651,7 +1680,7 @@ interface WorkloadGetToken {
 /**
 * Workload Identity Authentication Interface
 */
-type Workload = WorkloadConfig & ModuleReadiness & {
+type Workload = WorkloadConfig & ModuleReadiness & Required<Pick<ModuleReadiness, "isReady" | "ready">> & {
 	/**
 	* Returns a token for this workload configuration.
 	* The optional argument overrides the configured default scope.
@@ -1737,6 +1766,11 @@ type IAMConfig = {
 	*/
 	inboundUsers?: IAMInboundUsersConfig;
 	/**
+	* FrameworkConfig-only fallback that mints an IAM-owned deep link where access to an entitlement
+	* can be requested. A `requestUrl` written back into the catalog row by IAM takes precedence.
+	*/
+	entitlementRequestUrl?: (entitlement: Entitlement, type: EntitlementType, context: IAMEntitlementRequestUrlContext) => string | undefined;
+	/**
 	* Optional handler defaults. These are merged with per-call overrides in
 	* `iam.handler`, with per-call values taking precedence.
 	*/
@@ -1759,10 +1793,10 @@ type IAMConfig = {
 	* RemoteConfig/ECI intent: how access changes that occur inside the application are surfaced to the
 	* enterprise IAM/governance layer. Not configurable from application code.
 	*
-	* `'patch'`: outbound SCIM into the IAM tool keyed strictly by `externalId` (uses `url` as the
-	* destination base and `deltaAudience` for the outgoing workload client). Keeps the IAM tool's
-	* view fresh as the app grants/revokes access directly, so the tool can reconcile the echo
-	* against the originating request. See the README "IAM delta egress" section.
+	* `'patch'`: outbound SCIM into the IAM tool keyed by the App-owned catalog id carried as SCIM
+	* `externalId` (uses `url` as the destination base and `deltaAudience` for the outgoing workload client). Every observed runtime
+	* mutation that changes the IAM full-sync view egresses: user and entitlement upsert/delete, and
+	* access grant/revoke. See the README "IAM delta egress" section.
 	*
 	* When omitted, delta egress is disabled. The SDK only emits the signal; the enterprise's IAM
 	* tooling owns the response (flag, auto-revoke + notify, or audit). See `IamDeltaMode`.
@@ -1773,12 +1807,6 @@ type IAMConfig = {
 	* pushes to the destination (`url`). When omitted, the default workload server token is used.
 	*/
 	deltaAudience?: string;
-	/**
-	* Durable externalId -> destination provider-id mapping store for `delta:'patch'`. Wired by the
-	* application via `FrameworkStores.deltaIdMapStore` (a code/runtime capability, not a secret), so
-	* the patch adapter resolves each resource once and reuses the id thereafter.
-	*/
-	deltaIdMapStore?: IamDeltaIdMapStore;
 };
 /**
 * Per-endpoint enablement flag carried in RemoteConfig (Ops/ECI intent).
@@ -1786,6 +1814,10 @@ type IAMConfig = {
 type IAMEndpointFlag = {
 	enabled?: boolean;
 };
+type IAMEntitlementRequestUrlContext = {
+	request: Request;
+	tenantId?: string;
+};
 type IAMValidators = {
 	user: StandardSchemaV15<unknown, User>;
 	group: StandardSchemaV15<unknown, GroupResource>;
@@ -1936,9 +1968,9 @@ interface CreateUserOptions {
 */
 interface CreateGroupOptions {
 	/**
-	* External identifier for the group
+	* App-owned identifier for the group. Sent to the provider as SCIM `externalId`.
 	*/
-	externalId?: string;
+	id?: string;
 	/**
 	* Initial members to add to the group
 	*/
@@ -2052,45 +2084,43 @@ type IAM = IAMConfig & {
 	*/
 	delta?: IamDeltaEmitter;
 };
-type KmsKeyState = "pending" | "active" | "deprecated" | "revoked";
-type KmsPoolKind = "token" | "allocation";
-type KmsTokenKey = {
+type KmsKeyState = "pending" | "active" | "deprecated" | "rotated" | "revoked";
+type KmsKey = {
 	id: string;
 	state: KmsKeyState;
 	value?: string;
 	notBefore?: string;
 	notAfter?: string;
+	/** Control-plane lifecycle timestamps. Vaults omit these from personalized client grants. */
+	createdAt?: string;
+	activatedAt?: string;
+	deprecatedAt?: string;
+	rotatedAt?: string;
+	revokedAt?: string;
 	/** Control-plane metadata used for allocation policy and UI. Consumers should treat it as opaque. */
 	meta?: Record<string, unknown>;
 };
-type KmsTokenPoolDocument = {
-	kind: "token";
-	active: string;
-	keys: KmsTokenKey[];
+/** Personalized per-client view delivered by a secrets source. */
+type KmsPoolDocument = {
+	kind: "kms";
+	/** Omitted when the server has revoked the previous grant and no replacement is available yet. */
+	active?: string;
+	keys: KmsKey[];
 };
-/** Per-client allocation view delivered by a secrets source. */
-type KmsAllocationPoolView = {
-	kind: "allocation";
-	active: string;
-	keys: KmsTokenKey[];
-};
-type KmsPoolDocument = KmsTokenPoolDocument | KmsAllocationPoolView;
 type KmsAllocationStrategy = "spread" | "low-quota-first";
 type KmsAllocationPolicy = {
 	strategy?: KmsAllocationStrategy;
 	maxHoldersPerKey?: number;
+	/** Grace period during which a gracefully rotated key remains accepted. Defaults to 300 seconds. */
+	overlapSeconds?: number;
 };
-/** Control-plane allocation document stored by the vault. Clients receive a personalized view instead. */
-type KmsAllocationPoolDocument = {
-	kind: "allocation";
-	keys: KmsTokenKey[];
-	assignments: Record<string, string>;
-	policy?: KmsAllocationPolicy;
+/** Key-material document stored by the vault. Operational assignment and policy state is external. */
+type KmsPoolControlDocument = {
+	kind: "kms";
+	keys: KmsKey[];
 };
 /** ConfigSource-owned pointer to a KMS pool document. */
 type KmsPoolConfig = {
-	/** Pool semantics. Defaults to `token`. */
-	kind?: KmsPoolKind;
 	/** Named `ion.secrets` source. Omit to use the default `ion.secret` source. */
 	source?: string;
 	/** Secret path. Defaults to `/kms/{poolName}`. */
@@ -2098,13 +2128,16 @@ type KmsPoolConfig = {
 };
 /** ConfigSource-owned named KMS pool declarations. */
 type KmsConfig = Record<string, KmsPoolConfig>;
-type KmsPoolListener = (current: KmsTokenKey | undefined) => void;
+type KmsPoolListener = (current: KmsKey | undefined) => void;
 type KmsPool = {
-	/** Returns the usable token value, briefly awaiting only a locally scheduled imminent activation. */
-	value(): Promise<string>;
-	/** Timing-safe verification against the active token and usable deprecated overlap tokens. */
+	/**
+	* Returns the current granted key. Calls wait on one shared local subscription until a grant is
+	* available; repeated calls resolve from the local cache and never initiate a vault request.
+	*/
+	value(timeout?: number): Promise<string>;
+	/** Timing-safe verification against the active key and usable deprecated rotation-overlap keys. */
 	accepts(candidate: string): boolean;
-	/** Notifies immediately and whenever the selected active token changes. */
+	/** Notifies immediately and whenever the selected active key changes. */
 	subscribe(listener: KmsPoolListener): () => void;
 	beforeChange(listener: ChangeListener): () => void;
 	afterChange(listener: ChangeListener): () => void;
@@ -2121,12 +2154,9 @@ type Kms = ModuleReadiness & {
 	getPool(name: string): KmsPool;
 };
 /** Parse and fail closed on a personalized KMS pool document. */
-declare function parseKmsPoolDocument(value: unknown): KmsTokenPoolDocument;
-declare function parseKmsPoolDocument(value: unknown, expectedKind: "token"): KmsTokenPoolDocument;
-declare function parseKmsPoolDocument(value: unknown, expectedKind: "allocation"): KmsAllocationPoolView;
-declare function parseKmsPoolDocument(value: unknown, expectedKind: KmsPoolKind): KmsPoolDocument;
-/** Parse and fail closed on a control-plane allocation-pool document. */
-declare function parseKmsAllocationPool(value: unknown): KmsAllocationPoolDocument;
+declare function parseKmsPoolDocument(value: unknown): KmsPoolDocument;
+/** Parse and fail closed on a vault-stored KMS key-material document. */
+declare function parseKmsPoolControlDocument(value: unknown): KmsPoolControlDocument;
 type OtelSignalName = "traces" | "metrics" | "logs";
 type OtelProtocol = "http/protobuf" | "http/json";
 type OtelProviderType = "otlp" | "grafana-lgtm" | "datadog" | "splunk" | "elastic";
@@ -2170,7 +2200,7 @@ type OtelConfig = {
 	protocol?: OtelProtocol;
 	headers?: Record<string, string>;
 	apiKey?: string;
-	/** Name of a `RemoteConfig.kms` token pool used for exporter authentication. */
+	/** Name of a `RemoteConfig.kms` key pool used for exporter authentication. */
 	apiKeyPool?: string;
 	apiKeyHeader?: string;
 	oauth?: OtelOAuthClientCredentialsConfig;
@@ -2494,9 +2524,7 @@ declare function validationFailureResponse(issues: unknown, message: string): Re
 * @returns Merged configuration object
 */
 declare function mergeConfig<T extends Record<string, unknown>>(fromVault: T | undefined, fromCode: T | undefined, criticalFields?: string[]): T;
-/**
-* Strips // and /* *\/ comments from JSONC, respecting string literals.
-*/
+/** Strips // and /* *\/ comments from JSONC, respecting string literals. */
 declare function stripJsonComments(content: string): string;
 declare function parseJsonc<T>(content: string): T;
 /**
@@ -2849,6 +2877,58 @@ interface MagicLinkStore<TExtended = object> {
 	*/
 	delete(token: string): Promise<void>;
 }
+import { StandardSchemaV1 as StandardSchemaV17 } from "@standard-schema/spec";
+declare const DEFAULT_SECRET_MIME_TYPES: Readonly<Record<SecretFormat, string>>;
+type SecretTypeRegistryEntry = SecretContentType & {
+	id: string;
+	label?: string;
+};
+type SecretTypeInput<T> = {
+	id: string;
+	label?: string;
+	format: SecretFormat;
+	mimeType?: string;
+	schemaUrl?: string;
+	schema?: StandardSchemaV17<unknown, T>;
+};
+/**
+* Runtime contract for a custom secret type. The Standard Schema value is used only by server-side
+* parsing; `toRegistryEntry()` returns the serializable half that a vault editor can register.
+*/
+type SecretTypeDescriptor<T = unknown> = Readonly<{
+	id: string;
+	label?: string;
+	format: SecretFormat;
+	mimeType: string;
+	schemaUrl?: string;
+	schema?: StandardSchemaV17<unknown, T>;
+	toRegistryEntry(): SecretTypeRegistryEntry;
+}>;
+type InferSecretType<TType> = TType extends SecretTypeDescriptor<infer T> ? T : never;
+declare function defineSecretType<T>(input: SecretTypeInput<T> & {
+	schema: StandardSchemaV17<unknown, T>;
+}): SecretTypeDescriptor<T>;
+declare function defineSecretType<T>(input: SecretTypeInput<T>): SecretTypeDescriptor<T>;
+declare function defineSecretType(input: SecretTypeInput<unknown>): SecretTypeDescriptor<unknown>;
+declare function defaultSecretContentType(format?: SecretFormat): SecretContentType;
+/** Raised before decoding when a stored secret does not match the requested runtime contract. */
+declare class SecretContentTypeMismatchError extends Error {
+	readonly expected: SecretContentType;
+	readonly received: SecretContentType;
+	constructor(expected: SecretContentType, received: SecretContentType);
+}
+type SecretFormat = "jsonc" | "env" | "text" | "binary" | "yaml" | "toml" | "xml";
+/**
+* Self-describing content metadata persisted with a secret. `typeId` identifies an authoring preset;
+* decoding never depends on the preset registry because the resolved format/mime/schema travel with
+* the secret.
+*/
+type SecretContentType = {
+	format: SecretFormat;
+	mimeType: string;
+	schemaUrl?: string;
+	typeId?: string;
+};
 type Secret<T> = {
 	data: T;
 	metadata: MetaData;
@@ -2857,6 +2937,8 @@ type MetaData = {
 	path: string;
 	version: number;
 	created: Date;
+	/** Persisted write contract. Absent only on records written before type became mandatory. */
+	contentType?: SecretContentType;
 };
 type SecretsSourceType = "vault" | "azure" | "aws" | "gcp" | "dev";
 type SecretRequestSeverity = "low" | "medium" | "high" | "critical";
@@ -2878,6 +2960,24 @@ type SecretsOperationOptions = {
 	/** Optional timeout in milliseconds for this secrets operation. */
 	timeout?: number;
 };
+type SecretsWriteOptions = SecretsOperationOptions & {
+	/** Content contract stored with the secret and returned by all transports. Required on every write. */
+	contentType: SecretContentType;
+};
+type SecretHandle = {
+	/** Reads the canonical textual representation. Binary secrets reject this accessor. */
+	text(): Promise<string>;
+	/** Decodes JSONC. Other formats reject this accessor. */
+	json<T = unknown>(): Promise<T>;
+	/** Reads the canonical bytes. Text formats are UTF-8 encoded. */
+	bytes(): Promise<Uint8Array>;
+	/** Decodes an env/key=value secret. */
+	env(): Promise<Record<string, string>>;
+	/** Reads metadata without decoding the value. */
+	metadata(): Promise<MetaData>;
+	/** Decodes and validates using a runtime secret-type descriptor. */
+	parse<T>(type: SecretTypeDescriptor<T>): Promise<T>;
+};
 type SubscriptionMode = "fail-fast" | "wait";
 type SecretsSubscriptionOptions = SecretsOperationOptions & {
 	/**
@@ -2894,7 +2994,7 @@ type LfvCallbackHeaders = {
 	signature: string;
 };
 /**
-* Original LFV callback bytes and signature headers distributed between App processes. Consumers
+* Original LFV callback bytes and signature headers handed between App processes. Consumers
 * MUST independently verify this envelope against their own configured `verifyJwks`; the transport
 * is never a signature trust anchor.
 */
@@ -2902,20 +3002,17 @@ type LfvCallbackEnvelope = {
 	kind: LfvCallbackKind;
 	/** Normalized `serverUrl|path` routing key. */
 	key: string;
-	/** Random process/source identity used to suppress transport echo. */
-	originId: string;
 	rawBody: string;
 	headers: LfvCallbackHeaders;
 };
-type LfvCallbackEnvelopeListener = (envelope: LfvCallbackEnvelope) => void | Promise<void>;
 /**
-* Cross-process transport for signed LFV callback envelopes. The default SDK behavior remains the
-* in-process callback hub; applications opt into a transport (for example Redis Pub/Sub) through
-* FrameworkConfig.
+* Cross-process, single-consume mailbox for signed LFV OTP callbacks. The process that receives a
+* callback with no local waiter parks it by request id; the process that initiated the operation
+* takes it. TTL is mandatory so abandoned OTPs cannot accumulate.
 */
 type LfvCallbackTransport = {
-	publish(envelope: LfvCallbackEnvelope): Promise<void>;
-	subscribe(key: string, listener: LfvCallbackEnvelopeListener): Promise<() => void>;
+	put(requestId: string, envelope: LfvCallbackEnvelope, ttlMs: number): Promise<void>;
+	take(requestId: string): Promise<LfvCallbackEnvelope | undefined>;
 };
 /** Framework-only LFV runtime wiring. Live transports MUST never be supplied by RemoteConfig. */
 type FrameworkLfvConfig = {
@@ -2923,13 +3020,15 @@ type FrameworkLfvConfig = {
 };
 type SecretsSource = ReactiveHandle & ModuleReadiness & {
 	type: SecretsSourceType;
+	/** Creates a lazy, Bun.file-style handle. No I/O occurs until an accessor is awaited. */
+	get(path: string, options?: SecretsOperationOptions): SecretHandle;
 	getFullSecret: <T>(path: string, options?: SecretsOperationOptions) => Promise<Secret<T>>;
 	getSecret: <T>(path: string, options?: SecretsOperationOptions) => Promise<T>;
 	/**
 	* Write a secret at the given path.
 	* Implementations may throw for read-only or unsupported secret sources.
 	*/
-	putSecret: (path: string, value: Record<string, unknown>, options?: SecretsOperationOptions) => Promise<void>;
+	putSecret: (path: string, value: Record<string, unknown>, options: SecretsWriteOptions) => Promise<void>;
 	/**
 	* When set, the secret source supports change detection, reads the current value first, and calls onChange
 	* immediately with that value before watching for changes.
@@ -2991,12 +3090,14 @@ type Secrets = ModuleReadiness & {
 	listSecretsSources(): string[];
 	/** Gets a named secrets source client. Throws when missing. */
 	getSecretsSource(sourceName: string): SecretsSource;
+	/** Creates a lazy handle for a secret in a named source. */
+	get(sourceName: string, path: string, options?: SecretsOperationOptions): SecretHandle;
 	/** Reads a secret from a named secrets source client. */
 	getSecret<T>(sourceName: string, path: string, options?: SecretsOperationOptions): Promise<T>;
 	/** Reads full secret data + metadata from a named secrets source client. */
 	getFullSecret<T>(sourceName: string, path: string, options?: SecretsOperationOptions): Promise<Secret<T>>;
 	/** Writes a secret to a named secrets source client. */
-	putSecret(sourceName: string, path: string, value: Record<string, unknown>, options?: SecretsOperationOptions): Promise<void>;
+	putSecret(sourceName: string, path: string, value: Record<string, unknown>, options: SecretsWriteOptions): Promise<void>;
 	/** Deletes a secret from a named secrets source client. */
 	deleteSecret(sourceName: string, path: string, options?: SecretsOperationOptions): Promise<void>;
 	/** Lists child paths under a base path for a named secrets source client. */
@@ -3247,7 +3348,7 @@ type AzureSecretsConfig = {
 	*/
 	ttl?: number;
 };
-type ConfigSourceType = "vault" | "azure" | "aws" | "gcp";
+type ConfigSourceType = "vault" | "azure" | "aws" | "gcp" | "mirror";
 type ConfigSourceEnv = {
 	ION_CONFIG_TYPE?: ConfigSourceType;
 	ION_VAULT_URL?: string;
@@ -3263,6 +3364,7 @@ type ConfigSourceEnv = {
 	ION_VAULT_LFV_DELIVERY_ENDPOINT?: string;
 	ION_VAULT_LFV_VERIFY_JWKS?: string;
 	ION_VAULT_LFV_EVENTS_ENDPOINT?: string;
+	ION_VAULT_LFV_PATH?: string;
 	ION_VAULT_LFV_DELIVERY_TIMEOUT?: string;
 	ION_VAULT_LFV_RETRY_INTERVAL?: string;
 	ION_VAULT_LFV_WARN_INTERVAL?: string;
@@ -3287,6 +3389,8 @@ type ConfigSourceEnv = {
 	ION_AWS_WEBHOOK_URL?: string;
 	ION_AWS_TTL?: string;
 	ION_GCP_TTL?: string;
+	/** Complete upstream ConfigLocator for `ION_CONFIG_TYPE=mirror`, using existing names after this prefix. */
+	[key: `ION_FROM_${string}`]: string | undefined;
 };
 type VaultConfigLocator = {
 	type: "vault";
@@ -3338,30 +3442,18 @@ type GcpConfigLocator = {
 	type: "gcp";
 	gcpTtl?: number;
 };
-type ConfigLocator = VaultConfigLocator | AwsConfigLocator | AzureConfigLocator | GcpConfigLocator;
-/**
-* Narrow, serializable pointer a tenant stores to locate its RemoteConfig. Unlike the full
-* {@link ConfigLocator} (used only to bootstrap the ROOT config source from env/a trusted secret),
-* a `TenantConfigLocator` carries NO connection details or credentials. It resolves against secrets
-* sources already declared on the root ionite instance:
-* - `source` (optional): the name of a declared source in `ion.secrets`. When omitted, `ion.secret`
-*   (the default config-source-backed client) is used.
-* - `path`: the tenant-specific secret path within that source.
-* - `ttl` (optional): poll interval (ms) for the tenant config subscription.
-*
-* This keeps credentials/connection wiring on the root Ionite (ConfigSource-owned) and out of the tenant
-* store, and forces apps to declare their secrets sources up front rather than spinning them up
-* ad-hoc per tenant.
-*/
-type TenantConfigLocator = {
-	source?: string;
-	path: string;
-	ttl?: number;
+type MirrorConfigLocator = {
+	type: "mirror";
+	/** Authoritative upstream. Nested mirrors are rejected by runtime validation. */
+	from: ConfigLocator;
+	/** App-owned, write-capable mirror destination. */
+	to: VaultConfigLocator;
 };
+type ConfigLocator = VaultConfigLocator | AwsConfigLocator | AzureConfigLocator | GcpConfigLocator | MirrorConfigLocator;
 /**
-* Minimal handle needed to materialize a tenant's {@link ConfigSource} from a {@link TenantConfigLocator}.
-* Structurally satisfied by an `Ionite` instance (`ion`): the default `secret` client plus
-* the optional named `secrets` sources.
+* Minimal handle needed to materialize a config source from an already-configured secrets source.
+* Structurally satisfied by an `Ionite` instance (`ion`): the default `secret` client plus optional
+* named `secrets` sources.
 */
 type ConfigSourceResolver = {
 	secret: SecretsSource;
@@ -3446,24 +3538,22 @@ type AuthzConfig = {
 	*/
 	trustedProvisioningClients?: TrustedProvisioningClient[];
 	/**
-	* Code-declared catalog (Framework-only; a ConfigSource can never supply it). An in-memory,
-	* read-path definition source for code-authored groups/roles/permissions: never seeded or
-	* written to any store, unified with `catalogStore` and resource-derived entitlements on every
-	* read (lookup order code -> store -> derived), and immutable through SCIM (member grant/revoke
-	* allowed; metadata writes return 403 `mutability`). Accepts declarative arrays or a
-	* `defineCatalog(...)` result; validated/normalized at config apply. See `defineCatalog`.
+	* Code-declared catalog (Framework-only; a ConfigSource can never supply it). Supplies structural
+	* templates for code-authored groups/roles/permissions. Entries remain readable before
+	* materialization, then `catalogStore` rows own runtime presentation and IAM receipts while code
+	* continues to own structure. Accepts declarative arrays or a `defineCatalog(...)` result;
+	* validated/normalized at config apply. See `defineCatalog`.
 	*/
 	catalog?: CodeCatalog | CodeCatalogInput;
-	/** Durable catalog store for SCIM/IAM-sourced entitlement definitions (full SCIM CRUD). */
+	/** Runtime authority for grantable entitlement definitions, presentation, lifecycle, and IAM receipts. */
 	catalogStore?: AccessCatalogStore;
 	/** Granted roots (source of truth) used by SCIM/IAM orchestration and OAA projection. */
 	accessStore?: AccessAssignmentStore;
 	/** Derived closure index for fast `has*` checks; materialized from accessStore + catalogStore. */
 	accessIndex?: AccessIndex;
 	/**
-	* Read-through provider over the application's own resource data (teams, projects, ...), including
-	* optional derived-entitlement functions. The SDK never stores resources itself; see
-	* {@link ResourceProvider}.
+	* Read-through provider over the application's own resource data (teams, projects, ...). The SDK
+	* never stores resources itself; see {@link ResourceProvider}.
 	*/
 	resources?: ResourceProvider;
 	/**
@@ -3563,7 +3653,7 @@ type RemoteConfig = {
 	workload?: WorkloadConfig | WorkloadConfigMap | WorkloadIncomingOutgoing;
 	/** Optional named secrets-source configs available to this App instance. */
 	secrets?: SecretsModuleConfig;
-	/** ConfigSource-owned named managed token pools consumed through `ion.kms`. */
+	/** ConfigSource-owned named server-allocated key pools consumed through `ion.kms`. */
 	kms?: KmsConfig;
 	ciam?: CIAMConfig;
 	/** OpenTelemetry collector/exporter config loaded from ConfigSource. */
@@ -3643,7 +3733,7 @@ type FrameworkStores = {
 	customerStore?: CustomerStore<unknown>;
 	accessStore?: AccessAssignmentStore<unknown>;
 	accessIndex?: AccessIndex;
-	/** Code-declared catalog (read-path, in-memory; never stored). See `AuthzConfig.catalog`. */
+	/** Code-declared structural catalog templates. See `AuthzConfig.catalog`. */
 	catalog?: CodeCatalog | CodeCatalogInput;
 	catalogStore?: AccessCatalogStore;
 	/** Read-through {@link ResourceProvider} over the app's own resource data (never SDK-stored). */
@@ -3656,11 +3746,6 @@ type FrameworkStores = {
 	* provisioned/assigned access (`subjectType: 'workload'`). Authorization works without it.
 	*/
 	workloadIdentityStore?: WorkloadIdentityStore<unknown>;
-	/**
-	* Durable externalId -> destination provider-id cache for IAM delta `'patch'` egress. Optional; when
-	* absent, `delta:'patch'` reports not-ready (the adapter requires a mapping store).
-	*/
-	deltaIdMapStore?: IamDeltaIdMapStore;
 };
 type ModifiableFrameworkConfig = FrameworkConfig & {
 	setStores(stores: FrameworkStores): void;
@@ -3782,8 +3867,8 @@ type ConfigSource = {
 * built-in core schemas.
 */
 type CIAMValidators = {
-	customer: StandardSchemaV17<unknown, BaseCustomer> & {
-		validate(value: unknown): Promise<StandardSchemaV17.Result<BaseCustomer>>;
+	customer: StandardSchemaV18<unknown, BaseCustomer> & {
+		validate(value: unknown): Promise<StandardSchemaV18.Result<BaseCustomer>>;
 	};
 	callbackParams?: StandardSchemaWithValidate<OidcCallbackParams>;
 	idTokenClaims?: StandardSchemaWithValidate<IdTokenClaims>;
@@ -4128,16 +4213,16 @@ type CreateTenantRequestBase = {
 	companyId: string;
 	companyName: string;
 	environmentType: EnvironmentType;
-	/** Required at creation: the pointer used to materialize this tenant's ConfigSource. */
-	configLocator: TenantConfigLocator;
+	/** Optional until the tenant's ConfigSource has been provisioned. */
+	configLocator?: ConfigLocator;
 	email?: string;
 	webhookUrl?: string;
 	callbackUrl?: string;
 };
 /**
-* Body for creating a tenant (`POST ${basePath}`). All identity fields plus `configLocator` are
-* required — a tenant cannot exist without config. Idempotent by `id`: re-submitting the same `id`
-* re-applies the record (safe for provisioning retries).
+* Body for creating a tenant (`POST ${basePath}`). `configLocator` may be supplied immediately or
+* patched later after the tenant's ConfigSource has been provisioned. Idempotent by `id`:
+* re-submitting the same `id` re-applies the record (safe for provisioning retries).
 */
 type CreateTenantRequest<TExtended extends object = object> = CreateTenantRequestBase & TExtended;
 /**
@@ -4150,7 +4235,7 @@ type UpdateTenantRequest<TExtended extends object = object> = {
 	companyId?: string;
 	companyName?: string;
 	environmentType?: EnvironmentType;
-	configLocator?: TenantConfigLocator;
+	configLocator?: ConfigLocator;
 	email?: string;
 	webhookUrl?: string;
 	callbackUrl?: string;
@@ -4205,9 +4290,9 @@ type TenantValidators<
 	TUpdateTenantRequest extends UpdateTenantRequest = UpdateTenantRequest,
 	TTenantResponse extends TenantResponse = TenantResponse
 > = {
-	createTenantRequest: StandardSchemaV18<unknown, TCreateTenantRequest>;
-	updateTenantRequest: StandardSchemaV18<unknown, TUpdateTenantRequest>;
-	tenantResponse?: StandardSchemaV18<unknown, TTenantResponse>;
+	createTenantRequest: StandardSchemaV19<unknown, TCreateTenantRequest>;
+	updateTenantRequest: StandardSchemaV19<unknown, TUpdateTenantRequest>;
+	tenantResponse?: StandardSchemaV19<unknown, TTenantResponse>;
 };
 declare function isConfigLocator(value: unknown): value is ConfigLocator;
 type BaseTenant = {
@@ -4227,14 +4312,12 @@ type BaseTenant = {
 	createdAt: Date;
 	updatedAt: Date;
 	/**
-	* Serializable pointer used to materialize this tenant's ConfigSource. Resolves against the root
-	* ionite secrets sources ({@link TenantConfigLocator}); carries no connection details or credentials.
-	* Required: every tenant has config, so `createIon`/`tenantConfigSource` can rely on it without a
-	* runtime presence guard.
+	* Serializable descriptor used to materialize this tenant's ConfigSource. Tenant-management
+	* payloads must contain only credential-free locator fields. Optional until vault/config-source
+	* integration completes; runtime construction must reject or remain unavailable while absent.
 	*/
-	configLocator: TenantConfigLocator;
+	configLocator?: ConfigLocator;
 };
-type TenantFactory<TTenant extends BaseTenant = BaseTenant> = (tenant: TTenant) => Ionite;
 /**
 * A single-flight cache of per-tenant {@link Ionite} instances, supplied by the app.
 *
@@ -4306,6 +4389,14 @@ type BaseUser<TExtended = object> = BaseUserFields & {
 	*/
 	externalId?: string;
 	/**
+	* Optional destination service-provider id captured after IAM materializes this user.
+	*/
+	providerId?: string;
+	/**
+	* Optional IAM-owned deep link associated with this user receipt.
+	*/
+	requestUrl?: string;
+	/**
 	* Optional Enterprise Controlled ID: a system-of-record-owned identity correlator formatted as
 	* `ecid:<realm>:<opaque>` (realm = the minting authority's id). Correlates this account to a
 	* single identity across systems. Minted by the enterprise SOR (via an ECI), never by the app;
@@ -4480,6 +4571,11 @@ interface UserStore<TExtended = object> {
 	*/
 	get(id: string): Promise<BaseUser<TExtended> | undefined>;
 	/**
+	* Optional secondary-index lookup for the stable enterprise correlation key. Implementations that
+	* omit it remain correct; callers fall back to paged `list()` scans.
+	*/
+	getByExternalId?(externalId: string): Promise<BaseUser<TExtended> | undefined>;
+	/**
 	* Retrieve a user based on their SCIM attributes or SSO JWT Claims.
 	*
 	* @param user - The user to lookup by SCIM attributes or SSO JWT Claims
@@ -4515,7 +4611,12 @@ type AuthzEntityBase = {
 	name: string;
 	displayName?: string;
 	description: string;
-	externalId?: string;
+	/** Destination service-provider id captured after IAM materializes this entitlement. */
+	providerId?: string;
+	/** Provenance of the durable catalog row. Code entries are materialized with `source: 'code'`. */
+	source?: "code" | "app" | "scim";
+	/** A retired entitlement may be deleted by IAM after its grants have been removed. */
+	deprecated?: boolean;
 	metadata?: Record<string, unknown>;
 };
 type Resource = AuthzEntityBase & {
@@ -4545,6 +4646,8 @@ type SubjectTypeScoping = {
 type Permission = AuthzEntityBase & SubjectTypeScoping & {
 	/** True when this catalog entry should be exposed as requestable access in IAM tooling. */
 	requestable?: boolean;
+	/** IAM-owned deep link where a principal can request this entitlement, when the destination provides one. */
+	requestUrl?: string;
 	action?: string;
 	/** Canonical OAA permission types (maps to OAA `permission_type`). */
 	permissionTypes?: string[];
@@ -4556,12 +4659,16 @@ type Permission = AuthzEntityBase & SubjectTypeScoping & {
 type Role = AuthzEntityBase & SubjectTypeScoping & {
 	/** True when this catalog entry should be exposed as requestable access in IAM tooling. */
 	requestable?: boolean;
+	/** IAM-owned deep link where a principal can request this entitlement, when the destination provides one. */
+	requestUrl?: string;
 	/** Permissions this role confers (definitional). Roles are flat bundles — OAA has no nested-role edge. */
 	permissions?: Array<string | Permission>;
 };
 type Group = AuthzEntityBase & SubjectTypeScoping & {
 	/** True when this catalog entry should be exposed as requestable access in IAM tooling. */
 	requestable?: boolean;
+	/** IAM-owned deep link where a principal can request this entitlement, when the destination provides one. */
+	requestUrl?: string;
 	/** Nested child groups composed into this group (definitional). */
 	groups?: Array<string | Group>;
 	/** Roles this group confers (group is the principal). Projected as OAA `local_group` role assignments. */
@@ -4594,6 +4701,14 @@ type AuthzScimGroupType = OaaAccessTargetType;
 type AuthzScimGroupExtension = {
 	type?: AuthzScimGroupType;
 	requestable?: boolean;
+	/** Destination service-provider id written back by IAM. */
+	providerId?: string;
+	/** IAM-owned deep link for requesting this entitlement. Writable by IAM. */
+	requestUrl?: string;
+	/** Catalog-row provenance. Read-only to IAM. */
+	source?: "code" | "app" | "scim";
+	/** Whether the entitlement has been retired and can be deleted. Read-only to IAM. */
+	deprecated?: boolean;
 	description?: string;
 	/** Resource ids this entitlement is scoped to (the catalog `Group.resources` binding, by id). */
 	resources?: string[];
@@ -4629,23 +4744,22 @@ interface EntityStore<TEntity> {
 	* durability guarantee is required (e.g. SCIM write-through).
 	*/
 	set(entity: TEntity): ReadyAccessCatalogEntry<TEntity>;
-	delete(id: string): Promise<void>;
-	list(options?: ListOptions): Promise<ListResult<TEntity>>;
 	/**
-	* Optional `externalId` secondary lookup. When implemented, the SDK resolves SCIM
-	* `externalId eq "..."` filters through this index instead of a full `list()` scan (AUDIT_HISTORY.md §7.4).
-	* Returns the single entity with the given `externalId`, or `undefined` when none matches. Stores
-	* that omit it fall back to scanning `list()`.
+	* Atomic insert-if-absent operation. Catalog materialization uses this so concurrent IAM
+	* presentation edits can never be overwritten by a late code-template insert. Returns the
+	* existing row when one already exists.
 	*/
-	getByExternalId?(externalId: string): Promise<TEntity | undefined>;
+	insertIfAbsent(entity: TEntity): ReadyAccessCatalogEntry<TEntity>;
+	delete(id: string): Promise<void>;
+	list(options?: ListOptions): Promise<ListResult<TEntity>>;
 }
 /** The catalog entity kind a {@link CatalogChange} refers to. */
 type CatalogChangeKind = OaaAccessTargetType;
 /**
 * A reactive catalog change emitted AFTER a durable `set()`/`delete()` lands on the backing store.
-* `set` carries the persisted entity so subscribers can project exactly what was stored without an
-* extra read; `delete` carries only the id, which the SDK projects as an incremental OAA entity
-* delete (full incremental CRUD). A later full `oaa.sync` remains the reconciliation safety net.
+* `set` carries the persisted entity and prior value (`undefined` on insert); `delete` carries the
+* removed entity so downstream projections can delete the matching provider resource after the
+* local row is gone. A later full sync remains the reconciliation safety net.
 *
 * Resource changes are NOT catalog changes: resources live in the application's own store and are
 * signaled through {@link ResourceProvider.changed} instead.
@@ -4654,10 +4768,11 @@ type CatalogChange = {
 	op: "set";
 	kind: CatalogChangeKind;
 	entity: Group | Role | Permission;
+	previous: Group | Role | Permission | undefined;
 } | {
 	op: "delete";
 	kind: CatalogChangeKind;
-	id: string;
+	entity: Group | Role | Permission;
 };
 /** Listener invoked with a {@link CatalogChange} after a durable catalog write lands. */
 type CatalogChangeListener = (change: CatalogChange) => void;
@@ -4667,9 +4782,8 @@ type AccessCatalogStore = {
 	permissions: EntityStore<Permission>;
 	/**
 	* Reactive change subscription (the catalog analog of {@link ReactiveHandle}). When implemented,
-	* the SDK subscribes once at wiring time and projects each change to OAA. Stores that omit it do
-	* not drive incremental OAA projection; a later full `oaa.sync` still reconciles. Returns an
-	* unsubscribe function.
+	* the SDK subscribes once at wiring time and projects each change to OAA and ready IAM delta.
+	* Stores that omit it rely on later full sync/reconcile. Returns an unsubscribe function.
 	*/
 	afterChange?(listener: CatalogChangeListener): () => void;
 };
@@ -4686,20 +4800,8 @@ type ResourceChangeListener = (change: ResourceChange) => void;
 * Resources are app-domain rows the application already persists in its own database/ORM — they are
 * NOT authorization state, so the SDK never stores a copy. Instead the app wires a `ResourceProvider`
 * (via `FrameworkStores.resources` / `AuthzConfig.resources`) and the SDK reads through it for
-* closure expansion, SCIM Group projection, and OAA projection. There is no seeding step, no
-* dual-write on CRUD routes, and no lifecycle to keep in sync: `db.insert(...)` (plus a `changed`
-* signal) is the whole integration.
-*
-* **Resource-derived entitlements.** `entitlements(resource)` is an app-authored PURE function that
-* derives the per-resource requestable entitlement {@link Group}s (e.g. "Team X (member)") on demand.
-* Unlike catalog entitlements (definitions authored as rows in the {@link AccessCatalogStore}),
-* resource-derived groups are rules, not rows: their definitions are never stored, they appear in
-* SCIM Groups list/get and OAA projection automatically, and member grants against their ids expand
-* with the group's `resources` scope like any catalog group (grants against both kinds are stored
-* identically as access roots). Keep the function next to your catalog entitlement definitions so the
-* logic stays grep-able and debuggable — it is plain code the SDK calls, not configuration.
-* `entitlement(id)` is the deliberate, app-authored reverse resolver (derived group id -> group);
-* both must be provided together.
+* resource-scoped closure expansion and OAA projection. Grantable entitlements are durable
+* {@link AccessCatalogStore} rows; resource providers no longer synthesize entitlement definitions.
 */
 type ResourceProvider = {
 	/** Point lookup by resource id (e.g. `'team:t1'`). */
@@ -4712,22 +4814,9 @@ type ResourceProvider = {
 	*/
 	children?(id: string): Promise<Resource[]>;
 	/**
-	* Pure, synchronous derivation of a resource's requestable entitlement {@link Group}s. Called on
-	* demand (results are memoized alongside catalog adjacency and invalidated by `changed`); must be
-	* deterministic for a given resource. Requires `entitlement` to be provided as well.
-	*/
-	entitlements?(resource: Resource): Group[];
-	/**
-	* Reverse resolution of a resource-derived entitlement id to its {@link Group} (or `undefined`
-	* when the id is not a resource-derived entitlement). App-authored on purpose — the id scheme is
-	* the app's, and an explicit resolver keeps derivation traceable. Required when `entitlements` is
-	* provided.
-	*/
-	entitlement?(id: string): Promise<Group | undefined>;
-	/**
 	* Change signal invoked after the app's own resource write/delete lands. Drives adjacency-cache
-	* invalidation, targeted index reconciliation, and incremental OAA resource projection. Returns an
-	* unsubscribe function. Without it, drift is only repaired by a later full reconcile/sync.
+	* invalidation, targeted index reconciliation, and incremental OAA resource projection. Returns
+	* an unsubscribe function. Without it, drift is only repaired by a later full reconcile/sync.
 	*/
 	changed?(listener: ResourceChangeListener): () => void;
 };
@@ -5084,6 +5173,10 @@ type ReconcileReport = {
 */
 type Authz = {
 	oaa: OaaClient;
+	/** Read the effective catalog union (materialized rows plus unmaterialized code templates). */
+	entitlements: {
+		list(options?: ListOptions): Promise<ListResult<Entitlement>>;
+	};
 	/** The wired closure index powering `has*`, when the app provided one via stores. */
 	accessIndex?: AccessIndex;
 	has(subject: AccessRef<BaseUser>, targetType: OaaAccessTargetType, target: AccessRef<Group | Role | Permission>, resource?: AccessRef<Resource>, subjectType?: SubjectType): Promise<AuthzDecision>;
@@ -5379,6 +5472,14 @@ declare function listGenerator<T>(listFn: (start: number, limit: number) => Prom
 */
 declare function readyCatalogEntry<TEntity extends object>(entity: TEntity, write: Promise<void>): ReadyAccessCatalogEntry<TEntity>;
 /**
+* Persisted content contract for an ionite RemoteConfig document.
+*
+* The descriptor intentionally omits a runtime schema because applications may extend validation
+* through their configured Standard Schema validators. Use `toRegistryEntry()` when writing the
+* secret so the serializable content metadata travels across Vault, WebSocket, and LFV transports.
+*/
+declare const remoteConfigSecretType: SecretTypeDescriptor<RemoteConfig>;
+/**
 * Typed store-layer conflict (§5.9). Persistence stores throw this instead of a generic `Error` when
 * a create/uniqueness invariant is violated, so callers (SCIM, iam-delta, app code) can distinguish a
 * genuine conflict (map to HTTP 409, do not retry blindly) from a transient store/network failure
@@ -5422,7 +5523,7 @@ declare function normalizeTenantPathNamespace(namespace?: TenantPathNamespace):
 declare function normalizeTenantRoutingStrategy(strategy?: TenantRoutingStrategy): TenantPathRoutingStrategy;
 declare function matchTenantPath(pathname: string, namespace?: TenantPathNamespace): TenantPathMatch | null;
 declare function buildTenantPath(id: string, restPath?: string, namespace?: TenantPathNamespace): string;
-import { StandardSchemaV1 as StandardSchemaV19 } from "@standard-schema/spec";
+import { StandardSchemaV1 as StandardSchemaV110 } from "@standard-schema/spec";
 type RegisterSSOAppPayload = {
 	/** Redirect URIs for the client. */
 	redirectUris: string[];
@@ -5464,7 +5565,7 @@ type SSOAppRegistry = {
 	register: (payload: RegisterSSOAppPayload) => Promise<RegisterSSOAppResult>;
 };
 type SSOAppValidators = {
-	registerSSOAppPayload: StandardSchemaV19<unknown, RegisterSSOAppPayload>;
+	registerSSOAppPayload: StandardSchemaV110<unknown, RegisterSSOAppPayload>;
 };
 type RegisterIAMAppPayload = {
 	/** App/tenant identifier (same globally unique id used by the App tenant). */
@@ -5503,7 +5604,7 @@ type IAMAppRegistry = {
 	register: (payload: RegisterIAMAppPayload) => Promise<RegisterIAMAppResult>;
 };
 type IAMAppValidators = {
-	registerIAMAppPayload: StandardSchemaV19<unknown, RegisterIAMAppPayload>;
+	registerIAMAppPayload: StandardSchemaV110<unknown, RegisterIAMAppPayload>;
 };
 type LfvActionName = "read_secret" | "create_secret" | "update_secret" | "delete_secret" | "request_rotate" | "request_revoke" | "rotate_secret" | "revoke_secret" | "list_paths" | "list_secrets" | "read_metadata" | "remove_path";
 type LfvOtpRequest = {
@@ -5536,4 +5637,4 @@ type LfvErrorResponse = {
 };
 /** Generates a ULID */
 declare function generateULID(prefix?: string): string;
-export { workloadTokenResponseSchema, withValidate, warnLogger, waitOn, version, validationFailureResponse, userSchema, unionCatalogRead, trustedClientPermissionsForPrincipal, trimTrailingSlash, tokenResponseSchema, toCodeCatalog, stripJsonComments, stableConfigHash, silentLogger, serializeConfig, readyCatalogEntry, parseKmsPoolDocument, parseKmsAllocationPool, parseJsonc, parseEcid, oidcCallbackSchema, normalizeTenantRoutingStrategy, normalizeTenantPathNamespace, must, mergeConfig, matchTenantPath, listGenerator, list, jwtAssertionClaimsSchema, isStoreConflictError, isEcid, isConfigSourceError, isConfigLocator, isCodeCatalog, infoLogger, idTokenClaimsSchema, groupResourceSchema, generateULID, formatEcid, defineCatalog, defaultLogger, deepEqualPlain, decodeUser, debugLogger, configTrustedClientGrants, claimsToUser, buildTenantPath, assertValidSubjectTypeScoping, assertEcid, accessRootId, accessRefId, X509Certificate, WorkloadValidators, WorkloadTokenStore, WorkloadTokenResponse, WorkloadPrincipal, WorkloadIncomingOutgoing, WorkloadIdentityStore, WorkloadIdentity, WorkloadGetToken, WorkloadConfigMap, WorkloadConfig, WorkloadClient, Workload, WorkforceUser, VaultWorkloadAuthConfig, VaultWebSocketSecretsConfig, VaultWebSocketAuthHeader, VaultSecretsConfig, VaultLfvSecretsConfig, VaultConfigLocator, ValidateResult, UsersInboundHandlerConfig, UserStoreOptions, UserStore, UpdateTenantRequest, TrustedProvisioningClient, TrustedIdp, TokenValidationResult, TokenResponse, TenantWebhookPayload, TenantValidators, TenantStore, TenantStatus, TenantRoutingStrategy, TenantResponse, TenantPathRoutingStrategy, TenantPathNamespace, TenantPathMatch, TenantIonCache, TenantFactory, TenantConfigLocator, SubscriptionMode, SubjectTypeScoping, SubjectType, SubjectScope, SubjectRef, StoreConflictKind, StoreConflictError, StateCookie, StandardSchemaWithValidate, SessionStore, Session, ServerOnlyWorkloadConfig, SecretsValidators, SecretsSubscriptionOptions, SecretsSourceType, SecretsSourceMap, SecretsSourceConfig, SecretsSource, SecretsOperationOptions, SecretsModuleConfig, Secrets, SecretRequestSeverity, SecretLifecycleRequest, SecretEventName, SecretEventListener, SecretEvent, Secret, User as ScimUser, ScimServiceProviderConfig, ScimSchemaDefinition, ScimSchemaAttributeDefinition, Role2 as ScimRole, ScimResult, ScimResourceTypeSchemaExtension, ScimResourceType, ScimMutationSummary, ScimListResponse, Group2 as ScimGroup, ScimError, ScimAuthenticationScheme, SSOValidators, SSOHandlerConfig, SSOConfigFromCode, SSOConfig, SSOAppValidators, SSOAppRegistry, SSO, RoutingOptions, RouteModule, RouteFilterResult, Role, ResourceProvider, ResourceChangeListener, ResourceChange, Resource, ResolvedVaultLfvSecretsConfig, ResolvedRoute, RequireReadyResult, RemoteConfigRetryOptions, RemoteConfigRetryHook, RemoteConfigRetryContext, RemoteConfigLoadErrorKind, RemoteConfig, RegisterSSOAppResult, RegisterSSOAppPayload, RegisterSSOAppError, RegisterIAMAppResult, RegisterIAMAppPayload, RegisterIAMAppError, ReconcileReport, ReadyzEndpointConfig, ReadyAccessCatalogEntry, ReadinessReport, ReactiveHandle, Photo, PhoneNumber, Permission, ParsedEcid, PLATFORM_ASSIGNABLE_SUBJECT_TYPES, OtelSignalName, OtelSignalConfig, OtelProviderType, OtelProtocol, OtelOAuthClientCredentialsConfig, OtelMetricsSignalConfig, OtelLogRecord, OtelLogLevel, OtelLevels, OtelConfig, OtelAttributes, OtelAttributeValue, Otel, OidcCallbackParams, OaaSyncResult, OaaSyncOptions, OaaSyncInput, OaaClient, OaaAccessTargetType, OaaAccessChangeBatchItem, Name, ModuleReadinessState, ModuleReadiness, ModuleName, ModifiableFrameworkConfig, MetaData, MagicLinkStore, MagicLink, Logger, ListResult, ListOptions, ListFilter, LfvOtpResponse, LfvOtpRequest, LfvJwks, LfvErrorResponse, LfvErrorCode, LfvEd25519PublicJwk, LfvEd25519PrivateJwk, LfvCallbackTransport, LfvCallbackKind, LfvCallbackHeaders, LfvCallbackEnvelopeListener, LfvCallbackEnvelope, LfvActionRequestBase, LfvActionName, LfvActionAcceptedResponse, KmsTokenPoolDocument, KmsTokenKey, KmsPoolListener, KmsPoolKind, KmsPoolDocument, KmsPoolConfig, KmsPool, KmsKeyState, KmsConfig, KmsAllocationStrategy, KmsAllocationPoolView, KmsAllocationPoolDocument, KmsAllocationPolicy, Kms, JwtBearerWorkloadConfig, JWTAssertionClaims, IoniteValidators, IoniteUserExtension, IoniteErrorOptions, IoniteError, IoniteBase, Ionite, InMemoryTenantStoreOptions, IdentityResolution, IdTokenClaims, IamDeltaResourceType, IamDeltaReconcileResult, IamDeltaMode, IamDeltaIdMapStore, IamDeltaIdMapKey, IamDeltaEmitter, ION_TENANT_MANAGE, ION_SDK_PERMISSIONS, ION_SCIM_USER_EXTENSION_URN, ION_IAM_USERS_WRITE, ION_IAM_READ, ION_IAM_GROUPS_WRITE, ION_ENDPOINT_PERMISSIONS, ION_CIAM_MAGIC_LINK_CREATE, ION_CAPABILITIEZ_READ, ION_AUTHZ_OAA_SYNC, ION_AUTHZ_GROUP_SCHEMA, IAMValidators, IAMUsersInbound, IAMInboundUsersConfig, IAMInboundUserContext, IAMHandlerConfig, IAMGroupsOutbound, IAMGroupsInbound, IAMDiscoveryHandlerConfig, IAMDiscoveryContext, IAMDiscoveryConfig, IAMConfigFromCode, IAMConfig, IAMAppValidators, IAMAppRegistry, IAM, GroupsInboundHandlerConfig, GroupResource, GroupMember, Group, GcpSecretsConfig, GcpConfigLocator, FrameworkWorkloadIncomingOutgoing, FrameworkWorkloadConfigFromCode, FrameworkWorkloadConfig, FrameworkStores, FrameworkSecretsSourceConfig, FrameworkSecretsModuleConfig, FrameworkOtelConfig, FrameworkLfvConfig, FrameworkConfigInput, FrameworkConfig, EnvironmentType, EntityStore, EntitlementType, Entitlement, EnterpriseExtension, EndpointPermission, EndpointOperation, Email, EgressOutcome, EgressChannelOutcome, EffectiveEdge, EcidFormatError, ECID_SCHEME, DevSecretsConfig, DEFAULT_TENANT_UI_NAMESPACE, DEFAULT_TENANT_API_NAMESPACE, CustomerStoreOptions, CustomerStore, Customer, CreateUserOptions, CreateTenantRequest, CreateGroupOptions, ConfigSubscriptionOptions, ConfigSourceType, ConfigSourceResolver, ConfigSourceErrorInit, ConfigSourceError, ConfigSourceEnv, ConfigSource, ConfigLocator, ConfigErrorKind, ConfigChangeResult, ConfigChangeOptions, ConfigChangeCallback, ConfigApplyStatus, CodeCatalogNamespace, CodeCatalogInput, CodeCatalog, ClientCredentialsWorkloadConfig, ChangeListener, CatalogChangeListener, CatalogChangeKind, CatalogChange, CapabilityState, CapabilityKey, CapabilityEndpointUrls, CapabilitiezManifest, CachedWorkloadToken, CacheConfig, CIAMValidators, CIAMProviderType, CIAMProviderDescriptor, CIAMProviderConfig, CIAMProviderColors, CIAMProviderBranding, CIAMConfigFromCodeInput, CIAMConfigFromCode, CIAMConfig, CIAM, BaseWorkloadIdentity, BaseUser, BaseTenant, BaseCustomer, AzureSecretsConfig, AzureConfigLocator, AzureAuthMethod, AwsSecretsConfig, AwsConfigLocator, AuthzScimGroupType, AuthzScimGroupExtension, AuthzOaaConfig, AuthzEntityBase, AuthzDecision, AuthzConfig, Authz, AuthenticatedUser, AuthenticatedPrincipal, ApplicationValidators, Address, AccessStatus, AccessRef, AccessProvenance, AccessMutationStatus, AccessMutationResult, AccessIndex, AccessCheckTarget, AccessCheckResult, AccessCheckReason, AccessChange, AccessCatalogStore, AccessAssignmentStore };
+export { workloadTokenResponseSchema, withValidate, warnLogger, waitOn, version, validationFailureResponse, userSchema, unionCatalogRead, trustedClientPermissionsForPrincipal, trimTrailingSlash, tokenResponseSchema, toCodeCatalog, stripJsonComments, stableConfigHash, silentLogger, serializeConfig, remoteConfigSecretType, readyCatalogEntry, parseKmsPoolDocument, parseKmsPoolControlDocument, parseJsonc, parseEcid, oidcCallbackSchema, normalizeTenantRoutingStrategy, normalizeTenantPathNamespace, must, mergeConfig, mergeCodeCatalogEntity, materializeCodeCatalogEntity, matchTenantPath, listGenerator, list, jwtAssertionClaimsSchema, isStoreConflictError, isEcid, isConfigSourceError, isConfigLocator, isCodeCatalog, infoLogger, idTokenClaimsSchema, groupResourceSchema, getCodeCatalogEntity, generateULID, formatEcid, deprecateRetiredCodeCatalogRows, defineSecretType, defineCatalog, defaultSecretContentType, defaultLogger, deepEqualPlain, decodeUser, debugLogger, configTrustedClientGrants, claimsToUser, catalogEntityStore, buildTenantPath, assertValidSubjectTypeScoping, assertEcid, accessRootId, accessRefId, X509Certificate, WorkloadValidators, WorkloadTokenStore, WorkloadTokenResponse, WorkloadPrincipal, WorkloadIncomingOutgoing, WorkloadIdentityStore, WorkloadIdentity, WorkloadGetToken, WorkloadConfigMap, WorkloadConfig, WorkloadClient, Workload, WorkforceUser, VaultWorkloadAuthConfig, VaultWebSocketSecretsConfig, VaultWebSocketAuthHeader, VaultSecretsConfig, VaultLfvSecretsConfig, VaultConfigLocator, ValidateResult, UsersInboundHandlerConfig, UserStoreOptions, UserStore, UpdateTenantRequest, TrustedProvisioningClient, TrustedIdp, TokenValidationResult, TokenResponse, TenantWebhookPayload, TenantValidators, TenantStore, TenantStatus, TenantRoutingStrategy, TenantResponse, TenantPathRoutingStrategy, TenantPathNamespace, TenantPathMatch, TenantIonCache, SubscriptionMode, SubjectTypeScoping, SubjectType, SubjectScope, SubjectRef, StoreConflictKind, StoreConflictError, StateCookie, StandardSchemaWithValidate, SessionStore, Session, ServerOnlyWorkloadConfig, SecretsWriteOptions, SecretsValidators, SecretsSubscriptionOptions, SecretsSourceType, SecretsSourceMap, SecretsSourceConfig, SecretsSource, SecretsOperationOptions, SecretsModuleConfig, Secrets, SecretTypeRegistryEntry, SecretTypeInput, SecretTypeDescriptor, SecretRequestSeverity, SecretLifecycleRequest, SecretHandle, SecretFormat, SecretEventName, SecretEventListener, SecretEvent, SecretContentTypeMismatchError, SecretContentType, Secret, User as ScimUser, ScimServiceProviderConfig, ScimSchemaDefinition, ScimSchemaAttributeDefinition, Role2 as ScimRole, ScimResult, ScimResourceTypeSchemaExtension, ScimResourceType, ScimMutationSummary, ScimListResponse, Group2 as ScimGroup, ScimError, ScimAuthenticationScheme, SSOValidators, SSOHandlerConfig, SSOConfigFromCode, SSOConfig, SSOAppValidators, SSOAppRegistry, SSO, RoutingOptions, RouteModule, RouteFilterResult, Role, ResourceProvider, ResourceChangeListener, ResourceChange, Resource, ResolvedVaultLfvSecretsConfig, ResolvedRoute, RequireReadyResult, RemoteConfigRetryOptions, RemoteConfigRetryHook, RemoteConfigRetryContext, RemoteConfigLoadErrorKind, RemoteConfig, RegisterSSOAppResult, RegisterSSOAppPayload, RegisterSSOAppError, RegisterIAMAppResult, RegisterIAMAppPayload, RegisterIAMAppError, ReconcileReport, ReadyzEndpointConfig, ReadyAccessCatalogEntry, ReadinessReport, ReactiveHandle, Photo, PhoneNumber, Permission, ParsedEcid, PLATFORM_ASSIGNABLE_SUBJECT_TYPES, OtelSignalName, OtelSignalConfig, OtelProviderType, OtelProtocol, OtelOAuthClientCredentialsConfig, OtelMetricsSignalConfig, OtelLogRecord, OtelLogLevel, OtelLevels, OtelConfig, OtelAttributes, OtelAttributeValue, Otel, OidcCallbackParams, OaaSyncResult, OaaSyncOptions, OaaSyncInput, OaaClient, OaaAccessTargetType, OaaAccessChangeBatchItem, Name, ModuleReadinessState, ModuleReadiness, ModuleName, ModifiableFrameworkConfig, MirrorConfigLocator, MetaData, MagicLinkStore, MagicLink, Logger, ListResult, ListOptions, ListFilter, LfvOtpResponse, LfvOtpRequest, LfvJwks, LfvErrorResponse, LfvErrorCode, LfvEd25519PublicJwk, LfvEd25519PrivateJwk, LfvCallbackTransport, LfvCallbackKind, LfvCallbackHeaders, LfvCallbackEnvelope, LfvActionRequestBase, LfvActionName, LfvActionAcceptedResponse, KmsPoolListener, KmsPoolDocument, KmsPoolControlDocument, KmsPoolConfig, KmsPool, KmsKeyState, KmsKey, KmsConfig, KmsAllocationStrategy, KmsAllocationPolicy, Kms, JwtBearerWorkloadConfig, JWTAssertionClaims, IoniteValidators, IoniteUserExtension, IoniteErrorOptions, IoniteError, IoniteBase, Ionite, InferSecretType, InMemoryTenantStoreOptions, IdentityResolution, IdTokenClaims, IamDeltaResourceType, IamDeltaReconcileResult, IamDeltaReconcileInput, IamDeltaMode, IamDeltaEmitter, ION_TENANT_MANAGE, ION_SDK_PERMISSIONS, ION_SCIM_USER_EXTENSION_URN, ION_IAM_USERS_WRITE, ION_IAM_READ, ION_IAM_GROUPS_WRITE, ION_ENDPOINT_PERMISSIONS, ION_CIAM_MAGIC_LINK_CREATE, ION_CAPABILITIEZ_READ, ION_AUTHZ_OAA_SYNC, ION_AUTHZ_GROUP_SCHEMA, IAMValidators, IAMUsersInbound, IAMInboundUsersConfig, IAMInboundUserContext, IAMHandlerConfig, IAMGroupsOutbound, IAMGroupsInbound, IAMDiscoveryHandlerConfig, IAMDiscoveryContext, IAMDiscoveryConfig, IAMConfigFromCode, IAMConfig, IAMAppValidators, IAMAppRegistry, IAM, GroupsInboundHandlerConfig, GroupResource, GroupMember, Group, GcpSecretsConfig, GcpConfigLocator, FrameworkWorkloadIncomingOutgoing, FrameworkWorkloadConfigFromCode, FrameworkWorkloadConfig, FrameworkStores, FrameworkSecretsSourceConfig, FrameworkSecretsModuleConfig, FrameworkOtelConfig, FrameworkLfvConfig, FrameworkConfigInput, FrameworkConfig, EnvironmentType, EntityStore, EntitlementType, Entitlement, EnterpriseExtension, EndpointPermission, EndpointOperation, Email, EgressOutcome, EgressChannelOutcome, EffectiveEdge, EcidFormatError, ECID_SCHEME, DevSecretsConfig, DestinationReference, DEFAULT_TENANT_UI_NAMESPACE, DEFAULT_TENANT_API_NAMESPACE, DEFAULT_SECRET_MIME_TYPES, CustomerStoreOptions, CustomerStore, Customer, CreateUserOptions, CreateTenantRequest, CreateGroupOptions, ConfigSubscriptionOptions, ConfigSourceType, ConfigSourceResolver, ConfigSourceErrorInit, ConfigSourceError, ConfigSourceEnv, ConfigSource, ConfigLocator, ConfigErrorKind, ConfigChangeResult, ConfigChangeOptions, ConfigChangeCallback, ConfigApplyStatus, CodeCatalogNamespace, CodeCatalogInput, CodeCatalog, ClientCredentialsWorkloadConfig, ChangeListener, CatalogEntityKind, CatalogChangeListener, CatalogChangeKind, CatalogChange, CapabilityState, CapabilityKey, CapabilityEndpointUrls, CapabilitiezManifest, CachedWorkloadToken, CacheConfig, CIAMValidators, CIAMProviderType, CIAMProviderDescriptor, CIAMProviderConfig, CIAMProviderColors, CIAMProviderBranding, CIAMConfigFromCodeInput, CIAMConfigFromCode, CIAMConfig, CIAM, BaseWorkloadIdentity, BaseUser, BaseTenant, BaseCustomer, AzureSecretsConfig, AzureConfigLocator, AzureAuthMethod, AwsSecretsConfig, AwsConfigLocator, AuthzScimGroupType, AuthzScimGroupExtension, AuthzOaaConfig, AuthzEntityBase, AuthzDecision, AuthzConfig, Authz, AuthenticatedUser, AuthenticatedPrincipal, ApplicationValidators, Address, AccessStatus, AccessRef, AccessProvenance, AccessMutationStatus, AccessMutationResult, AccessIndex, AccessCheckTarget, AccessCheckResult, AccessCheckReason, AccessChange, AccessCatalogStore, AccessAssignmentStore };