@cosmicdrift/kumiko-bundled-features 0.336.1 → 0.338.0

package/dist/agent-tools/agent-manifest.js

@@ -6,14 +6,38 @@ import * as z from "zod";
 function entryAsLabels(entry) {
     return Object.fromEntries(Object.entries(entry).map(([locale, value]) => [locale, translationValueOtherText(value)]));
 }
+const labelsIndexByTranslations = new WeakMap();
+/** Every tail starting at a key boundary (`:` or `.`, with and without the
+ *  separator) maps to the labels of the first key that ends with it. */
+function buildSuffixIndex(translations) {
+    const index = new Map();
+    for (const [key, entry] of Object.entries(translations)) {
+        const labels = entryAsLabels(entry);
+        const addTail = (start) => {
+            const tail = key.slice(start);
+            if (!index.has(tail))
+                index.set(tail, labels);
+        };
+        addTail(0);
+        for (let position = 0; position < key.length; position++) {
+            if (key[position] === ":" || key[position] === ".") {
+                addTail(position);
+                addTail(position + 1);
+            }
+        }
+    }
+    return index;
+}
 /** Translation keys carry a feature prefix the manifest can't reconstruct
- *  (`showcase:entity:item:field:title`), so match on the suffix instead. */
+ *  (`showcase:entity:item:field:title`), so match on the suffix instead. The
+ *  suffix must start at a `:` or `.` boundary of the key. */
 function labelsForSuffix(translations, suffix) {
-    for (const [key, labels] of Object.entries(translations)) {
-        if (key === suffix || key.endsWith(suffix))
-            return entryAsLabels(labels);
+    let index = labelsIndexByTranslations.get(translations);
+    if (index === undefined) {
+        index = buildSuffixIndex(translations);
+        labelsIndexByTranslations.set(translations, index);
     }
-    return {};
+    return index.get(suffix) ?? {};
 }
 /** Nav/screen/workspace gating is opt-in: no rule means visible to everyone
  *  (NavDefinition.access). Handlers are the opposite — `hasAccess` is
@@ -205,6 +229,9 @@ function lastSegment(qualifiedId) {
     const idx = qualifiedId.lastIndexOf(":");
     return idx === -1 ? qualifiedId : qualifiedId.slice(idx + 1);
 }
+function detailIdParam(screen) {
+    return screen.type === "projectionDetail" ? (screen.idParam ?? "id") : "id";
+}
 function buildScreens(screens, navs, workspaces, translations, roles, visibleNavIds) {
     const allNavs = [...navs.values()];
     const result = [];
@@ -239,8 +266,8 @@ function buildScreens(screens, navs, workspaces, translations, roles, visibleNav
                 description: labelsForSuffix(translations, screen.description)["en"] ?? screen.description,
             }),
             ...("entity" in screen && screen.entity !== undefined && { entity: screen.entity }),
-            // A detail screen takes the row id; everything else is parameterless.
-            params: screen.detailFor !== undefined ? ["id"] : [],
+            // A detail screen takes the row id under its idParam; everything else is parameterless.
+            params: screen.detailFor !== undefined ? [detailIdParam(screen)] : [],
             workspaces: screenWorkspaces,
             ...(screen.detailFor !== undefined && { detailFor: screen.detailFor }),
             ...("handler" in screen && typeof screen.handler === "string" && { handler: screen.handler }),

package/dist/agent-tools/tool-catalog.js

@@ -1,4 +1,4 @@
-import { hasAccess } from "@cosmicdrift/kumiko-framework/engine";
+import { hasAccess, normalizeAccessEntry } from "@cosmicdrift/kumiko-framework/engine";
 import { FILTER_OPS, isRecord } from "./filter-ops.js";
 const MAX_TOOL_NAME_LENGTH = 64;
 /** Field types that declare `filterable` (per `packages/framework/src/engine/types/fields.ts`).
@@ -74,14 +74,28 @@ function isDetailHandlerQn(qn, entityName) {
 function isExplicitlyAgentHidden(def) {
     return def.agent?.expose === false;
 }
-function addToolsForListHandler(registry, qn, entityName, entity, sink) {
+/** The model's filters feed the WHERE clause, and only the output is field-filtered — a field
+ *  whose read access is role- or row-restricted would leak through `totalCount` and hit/miss
+ *  probing. Only fields every one of these roles may read without a row condition are offered. */
+function isReadableWithoutRowCondition(field, roles) {
+    const accessMap = normalizeAccessEntry(field.access?.read);
+    if (!accessMap || Object.keys(accessMap).length === 0)
+        return true;
+    return roles.every((role) => accessMap[role] === "all");
+}
+/** Entity CRUD tools are registry-derived, so an explicit `agent.risk` on the handler is read
+ *  here; without a hint the read tools stay "low". */
+function entityHandlerRisk(registry, qn) {
+    return registry.getAllQueryHandlers().get(qn)?.agent?.risk ?? "low";
+}
+function addToolsForListHandler(registry, qn, entityName, entity, roles, sink) {
     const searchableFields = registry.getSearchableFields(entityName);
     if (searchableFields.length > 0) {
         const tool = buildSearchTool(entityName, searchableFields);
         addTool(sink, tool, { kind: "search", entityName, qn });
     }
     for (const [fieldName, field] of Object.entries(entity.fields)) {
-        if (!isFilterable(field))
+        if (!isFilterable(field) || !isReadableWithoutRowCondition(field, roles))
             continue;
         const fieldSchema = jsonSchemaTypeForField(field);
         if (!fieldSchema)
@@ -98,7 +112,7 @@ function entityDisplayLabel(entity, entityName, locale) {
         return label;
     return entityName;
 }
-function buildGetTool(entityName, qn, label) {
+function buildGetTool(entityName, qn, label, risk) {
     return {
         tool: {
             name: `get_${entityName}`,
@@ -110,7 +124,7 @@ function buildGetTool(entityName, qn, label) {
                 additionalProperties: false,
             },
         },
-        descriptor: { kind: "server", op: "query", qn, risk: "low", entity: entityName, detail: true },
+        descriptor: { kind: "server", op: "query", qn, risk, entity: entityName, detail: true },
     };
 }
 function buildListInputSchema(searchableFields, filterableFields) {
@@ -140,7 +154,7 @@ function buildListInputSchema(searchableFields, filterableFields) {
     properties["limit"] = { type: "integer", minimum: 1, maximum: 200 };
     return { type: "object", properties, required: [], additionalProperties: false };
 }
-function buildListTool(entityName, qn, label, searchableFields, filterableFields) {
+function buildListTool(entityName, qn, label, searchableFields, filterableFields, risk) {
     const descriptionParts = [`List ${label} records.`];
     if (searchableFields.length > 0) {
         descriptionParts.push(`Free-text search over: ${searchableFields.join(", ")}.`);
@@ -159,16 +173,22 @@ function buildListTool(entityName, qn, label, searchableFields, filterableFields
             kind: "server",
             op: "query",
             qn,
-            risk: "low",
+            risk,
             entity: entityName,
             list: { searchableFields, filterableFields },
         },
     };
 }
-function filterableFieldsOf(entity) {
+function filterableFieldsOf(entity, definition, roles) {
     if (!entity)
         return [];
-    return entity.fields.filter((field) => field.filterable === true).map((field) => field.name);
+    return entity.fields
+        .filter((field) => field.filterable === true)
+        .map((field) => field.name)
+        .filter((name) => {
+        const fieldDefinition = definition?.fields[name];
+        return fieldDefinition !== undefined && isReadableWithoutRowCondition(fieldDefinition, roles);
+    });
 }
 function compareByCodePoint(a, b) {
     return a < b ? -1 : a > b ? 1 : 0;
@@ -206,6 +226,25 @@ export function toolNameForQn(qn) {
     const sanitized = joined.replace(/[^A-Za-z0-9_]/g, "_").replace(/_+/g, "_");
     return sanitized.slice(0, MAX_TOOL_NAME_LENGTH);
 }
+// FNV-1a: only needs to be stable and well-spread, not collision-proof — a hash clash
+// on top of a name clash falls through to the sink's drop-later-tool guard.
+function shortQnHash(qn) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < qn.length; index++) {
+        hash = Math.imul(hash ^ qn.charCodeAt(index), 0x01000193) >>> 0;
+    }
+    return hash.toString(16).padStart(8, "0");
+}
+/** Sanitizing, verb-dropping and truncation make distinct QNs share a tool name; the
+ *  first QN in manifest order keeps the plain name, later ones get a QN-hash suffix so
+ *  no handler silently disappears from the catalog. */
+function uniqueToolNameForQn(qn, usedNames) {
+    const plainName = toolNameForQn(qn);
+    if (!usedNames.has(plainName))
+        return plainName;
+    const hashSuffix = `_${shortQnHash(qn)}`;
+    return `${plainName.slice(0, MAX_TOOL_NAME_LENGTH - hashSuffix.length)}${hashSuffix}`;
+}
 export const OPEN_FORM_TOOL_NAME = "open_form";
 function buildNavigateTool(manifest) {
     const entityScreens = new Map();
@@ -302,7 +341,7 @@ function addRegistrySearchTools(registry, roleFilter, denyQns, sink) {
         const entity = registry.getEntity(entityName);
         if (!entity)
             continue;
-        addToolsForListHandler(registry, qn, entityName, entity, sink);
+        addToolsForListHandler(registry, qn, entityName, entity, roleFilter.roles, sink);
     }
 }
 function collectEntityHandlerQns(registry, roleFilter, denyQns) {
@@ -333,21 +372,21 @@ function collectEntityHandlerQns(registry, roleFilter, denyQns) {
     }
     return { detailQnByEntity, listQnByEntity, entityListDetailQns };
 }
-function addGetTools(detailQnByEntity, entityByName, locale, sink) {
+function addGetTools(registry, detailQnByEntity, entityByName, locale, sink) {
     const getEntries = [...detailQnByEntity.entries()].sort((a, b) => compareByCodePoint(a[0], b[0]));
     for (const [entityName, qn] of getEntries) {
         const label = entityDisplayLabel(entityByName.get(entityName), entityName, locale);
-        const { tool, descriptor } = buildGetTool(entityName, qn, label);
+        const { tool, descriptor } = buildGetTool(entityName, qn, label, entityHandlerRisk(registry, qn));
         addTool(sink, tool, descriptor);
     }
 }
-function addListTools(registry, listQnByEntity, entityByName, locale, sink) {
+function addListTools(registry, listQnByEntity, entityByName, roles, locale, sink) {
     const listEntries = [...listQnByEntity.entries()].sort((a, b) => compareByCodePoint(a[0], b[0]));
     for (const [entityName, qn] of listEntries) {
         const label = entityDisplayLabel(entityByName.get(entityName), entityName, locale);
         const searchableFields = registry.getSearchableFields(entityName);
-        const filterableFields = filterableFieldsOf(entityByName.get(entityName));
-        const { tool, descriptor } = buildListTool(entityName, qn, label, searchableFields, filterableFields);
+        const filterableFields = filterableFieldsOf(entityByName.get(entityName), registry.getEntity(entityName), roles);
+        const { tool, descriptor } = buildListTool(entityName, qn, label, searchableFields, filterableFields, entityHandlerRisk(registry, qn));
         addTool(sink, tool, descriptor);
     }
 }
@@ -359,7 +398,7 @@ function addQueryHandlerTools(manifest, entityListDetailQns, denyQns, sink) {
             continue;
         if (entityListDetailQns.has(handler.qn))
             continue;
-        const name = toolNameForQn(handler.qn);
+        const name = uniqueToolNameForQn(handler.qn, sink.usedNames);
         addTool(sink, { name, description: handlerDescription(handler), inputSchema: handler.inputSchema }, {
             kind: "server",
             op: "query",
@@ -375,7 +414,7 @@ function addWriteHandlerTools(manifest, detailQnByEntity, denyQns, sink) {
             continue;
         if (denyQns.has(handler.qn))
             continue;
-        const name = toolNameForQn(handler.qn);
+        const name = uniqueToolNameForQn(handler.qn, sink.usedNames);
         const detailQn = handler.entity !== undefined ? detailQnByEntity.get(handler.entity) : undefined;
         const injectsVersion = detailQn !== undefined && schemaRequiresField(handler.inputSchema, "version");
         const inputSchema = injectsVersion
@@ -436,8 +475,8 @@ export function buildToolCatalog(registry, manifest, options) {
     const denyQns = new Set(options.denyQns ?? []);
     addRegistrySearchTools(registry, roleFilter, denyQns, sink);
     const { detailQnByEntity, listQnByEntity, entityListDetailQns } = collectEntityHandlerQns(registry, roleFilter, denyQns);
-    addGetTools(detailQnByEntity, entityByName, locale, sink);
-    addListTools(registry, listQnByEntity, entityByName, locale, sink);
+    addGetTools(registry, detailQnByEntity, entityByName, locale, sink);
+    addListTools(registry, listQnByEntity, entityByName, roleFilter.roles, locale, sink);
     addQueryHandlerTools(manifest, entityListDetailQns, denyQns, sink);
     if (options.mode !== "read-only") {
         addWriteHandlerTools(manifest, detailQnByEntity, denyQns, sink);

package/dist/audit/handlers/list.query.js

@@ -27,15 +27,19 @@ function buildDateRange(from, to) {
         range.lte = Temporal.Instant.from(to);
     return range;
 }
+function escapeLikePattern(value) {
+    return value.replace(/[\\%_]/g, (m) => `\\${m}`);
+}
 function buildAuditWhere(tenantId, p) {
     const where = { tenantId };
     if (p.aggregateType)
         where["aggregateType"] = p.aggregateType;
     if (p.aggregateId)
         where["aggregateId"] = p.aggregateId;
-    const type = p.eventType ?? p.search;
-    if (type)
-        where["type"] = type;
+    if (p.eventType)
+        where["type"] = p.eventType;
+    else if (p.search)
+        where["type"] = { like: `%${escapeLikePattern(p.search)}%` };
     if (p.userId)
         where["createdBy"] = p.userId;
     const range = buildDateRange(p.from, p.to);

package/dist/auth-email-password/handlers/invite-accept-with-login.write.js

@@ -53,6 +53,7 @@ export function createInviteAcceptWithLoginHandler(opts = {}) {
         access: { roles: ["anonymous"] },
         rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
         escapeHatch: {
+            grants: ["unsafeRaw"],
             reason: "Anonymous invite-accept has no session in the invited tenant yet — checks existing " +
                 "membership via ctx.queryAs(SYSTEM, tenant:query:memberships) of the invitation's tenant. " +
                 "Also reads the pending invitation by id (the invitee is not yet a member of the " +

package/dist/auth-email-password/handlers/invite-accept.write.js

@@ -51,6 +51,7 @@ export function createInviteAcceptHandler() {
         },
         agent: { expose: false },
         escapeHatch: {
+            grants: ["unsafeRaw"],
             reason: INVITE_ACCEPT_ESCAPE_HATCH_REASON,
         },
         // kumiko-lint-ignore complexity-budget invite branches (auth/anon/burn) stay in one handler

package/dist/auth-email-password/handlers/invite-info.query.js

@@ -34,6 +34,7 @@ export const inviteInfoQuery = defineQueryHandler({
     rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
     agent: { expose: false },
     escapeHatch: {
+        grants: ["unsafeRaw"],
         reason: READ_PENDING_INVITATION_REASON,
     },
     description: "Anonymous, read-only invite lookup for the invite-acceptance page: reveals the invited " +

package/dist/auth-email-password/handlers/invite-signup-complete.write.js

@@ -51,6 +51,7 @@ export function createInviteSignupCompleteHandler() {
         rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
         agent: { expose: false },
         escapeHatch: {
+            grants: ["unsafeRaw", "globalWrites"],
             reason: INVITE_SIGNUP_COMPLETE_ESCAPE_HATCH_REASON,
         },
         handler: async (event, ctx) => {

package/dist/auth-email-password/handlers/signup-confirm.write.js

@@ -78,6 +78,7 @@ export function createSignupConfirmHandler() {
         rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
         agent: { expose: false },
         escapeHatch: {
+            grants: ["unsafeRaw", "systemIdentity"],
             reason: SIGNUP_CONFIRM_PROVISION_REASON,
         },
         handler: async (event, ctx) => {

package/dist/auth-email-password/handlers/signup-request.write.js

@@ -55,7 +55,7 @@ export function createSignupRequestHandler(opts) {
         access: { roles: ["anonymous"] },
         rateLimit: { per: "ip+handler", limit: 10, windowSeconds: 60 },
         description: "Starts magic-link self-registration by mailing a fresh activation link to an address and invalidating any link still outstanding for it; the answer looks the same whether or not the address is already registered.",
-        escapeHatch: { reason: HANDOVER_GRANT_VERIFY_REASON },
+        escapeHatch: { reason: HANDOVER_GRANT_VERIFY_REASON, grants: ["unsafeRaw"] },
         handler: async (event, ctx) => {
             // Silent no-op when off, matching the route's own always-200
             // anti-enumeration contract (registerTokenRequestRoute swallows every

package/dist/auth-email-password/seeding.js

@@ -151,6 +151,12 @@ export async function seedAdmin(db, options) {
     return { id: userId };
 }
 function compareInsertedAt(a, b) {
+    // selectMany<ActiveUserRow> is an unchecked row-shape claim. A codec that
+    // yields another type would make both comparisons false and silently fall
+    // back to id order, which can crown the younger duplicate as survivor.
+    if (typeof a.epochNanoseconds !== "bigint" || typeof b.epochNanoseconds !== "bigint") {
+        throw new Error("compareInsertedAt: user.insertedAt is not a Temporal.Instant");
+    }
     if (a.epochNanoseconds < b.epochNanoseconds)
         return -1;
     if (a.epochNanoseconds > b.epochNanoseconds)

package/dist/auth-email-password/web/invite-accept-screen.js

@@ -22,6 +22,9 @@ import { csrfHeader } from "./auth-client.js";
 import { resolvePostAuthHref } from "./auth-form-logic.js";
 import { AuthCard, useUrlToken } from "./auth-form-primitives.js";
 import { SessionContext, UNAUTHENTICATED } from "./session.js";
+function isMfaPending(data) {
+    return data.tenantId === undefined;
+}
 function grantedRoles(data) {
     if (data.user?.roles !== undefined)
         return data.user.roles;
@@ -46,7 +49,7 @@ export function InviteAcceptScreen({ title, token: tokenProp, loggedInHref = "/"
     // challenge / setup requirement, but no session cookie was minted: send the
     // user to the login screen (now a member) instead of a tenant URL.
     const finishAccept = (data) => {
-        if (data.mfaRequired === true || data.mfaSetupRequired === true) {
+        if (isMfaPending(data)) {
             window.location.assign(loginHref);
             return;
         }

package/dist/auth-mfa/handlers/enable-start-preauth.write.js

@@ -30,6 +30,7 @@ export function createEnableStartPreauthHandler(opts) {
         // Same secret-bearing result as enable-start.
         agent: { expose: false },
         escapeHatch: {
+            grants: ["unsafeRaw"],
             reason: ENABLE_START_PREAUTH_TENANT_REASON,
         },
         handler: async (event, ctx) => {

package/dist/auth-mfa/handlers/enable-start.write.js

@@ -9,6 +9,18 @@ import { signMfaSetupToken } from "../mfa-setup-token.js";
 import { buildOtpauthUri } from "../otpauth-uri.js";
 import { generateRecoveryCodes, hashRecoveryCodes } from "../recovery-codes.js";
 import { generateTotpSecret } from "../totp.js";
+const FALLBACK_ACCOUNT_LABEL = "account";
+// The authenticator app shows this label, so an internal user id must never leak into it.
+function readableAccountLabel(me) {
+    if (typeof me !== "object" || me === null)
+        return FALLBACK_ACCOUNT_LABEL;
+    for (const field of ["email", "displayName"]) {
+        const value = Reflect.get(me, field);
+        if (typeof value === "string" && value.length > 0)
+            return value;
+    }
+    return FALLBACK_ACCOUNT_LABEL;
+}
 // Stateless setup: no `userMfa` row is created here. The generated secret +
 // recovery-code hashes are signed into a short-lived `setupToken` (see
 // mfa-setup-token.ts) that `enable-confirm` verifies. An abandoned setup
@@ -41,8 +53,7 @@ export function createEnableStartHandler(opts) {
             if (!accountLabel) {
                 // The declarative secretMint screen has no client component left to
                 // read the session email off — derive the otpauth label server-side.
-                const me = (await ctx.queryAs(event.user, UserQueries.me, {})); // @cast-boundary engine-payload
-                accountLabel = me?.email ?? event.user.id;
+                accountLabel = readableAccountLabel(await ctx.queryAs(event.user, UserQueries.me, {}));
             }
             const secret = generateTotpSecret();
             const recoveryCodes = generateRecoveryCodes();

package/dist/auth-mfa/hmac-token-codec.js

@@ -7,15 +7,15 @@ function hmacSign(input, secret) {
 // minted for one MFA step from verifying as another (e.g. a preauth-setup token
 // replayed as a challenge token), since both share the same secret and payload shape.
 export function createHmacTokenCodec(domain, isPayload) {
-    function isEncodedBody(value) {
+    function splitEncodedBody(value) {
         if (typeof value !== "object" || value === null)
-            return false;
+            return null;
         const v = value;
         const expiresAtMs = v["expiresAtMs"];
         if (typeof expiresAtMs !== "number")
-            return false;
+            return null;
         const { expiresAtMs: _drop, ...rest } = v;
-        return isPayload(rest);
+        return isPayload(rest) ? { payload: rest, expiresAtMs } : null;
     }
     return {
         sign(payload, ttlMinutes, secret, now = Temporal.Now.instant()) {
@@ -46,14 +46,13 @@ export function createHmacTokenCodec(domain, isPayload) {
             catch {
                 return { ok: false, reason: "malformed" };
             }
-            if (!isEncodedBody(parsed))
+            const body = splitEncodedBody(parsed);
+            if (!body)
                 return { ok: false, reason: "malformed" };
-            if (Temporal.Instant.compare(now, Temporal.Instant.fromEpochMilliseconds(parsed.expiresAtMs)) >
-                0) {
+            if (Temporal.Instant.compare(now, Temporal.Instant.fromEpochMilliseconds(body.expiresAtMs)) > 0) {
                 return { ok: false, reason: "expired" };
             }
-            const { expiresAtMs, ...payload } = parsed;
-            return { ok: true, payload: payload, expiresAtMs };
+            return { ok: true, payload: body.payload, expiresAtMs: body.expiresAtMs };
         },
     };
 }

package/dist/auth-mfa/web/mfa-setup-preauth-screen.js

@@ -1,5 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // @runtime client
+// Consumers that type-check this source never include the ambient declaration on their own.
+/// <reference path="./qrcode-browser.d.ts" />
 // Pre-auth twin of the declarative auth-mfa-enable secretMint screen: a user
 // blocked at login by MFA enforcement and not yet enrolled lands here
 // straight out of the login flow — there is no session yet. Identity comes

package/dist/billing-foundation/aggregate-id.d.ts

@@ -18,3 +18,5 @@ export declare function paymentAggregateId(tenantId: string): string;
  *  providerEventId)` rather than the event-store's bigserial `event.id` (not
  *  a UUID) or the shared per-tenant aggregateId (one row per payment). */
 export declare function paymentRowId(tenantId: string, providerName: string, providerEventId: string): string;
+/** Stream id of one unmatched termination declaration, derived from its request id. */
+export declare function terminationUnmatchedAggregateId(requestId: string): string;

package/dist/billing-foundation/aggregate-id.js

@@ -16,6 +16,9 @@ const PAYMENT_NAMESPACE = "dec0b897-646d-4da3-be3c-e9a35a83f4e0";
  *  UUID, so it can't back a uuid-typed PK. Generated 2026-09-11, set in
  *  stone (same rationale as the two namespaces above). */
 const PAYMENT_ROW_NAMESPACE = "3a1c9f4e-6b2d-4c8a-9e5f-7d4b1a2c8e6f";
+/** Namespace for the system-tenant stream of an unmatched termination
+ *  declaration (one stream per request). Generated 2026-10-03, set in stone. */
+const TERMINATION_UNMATCHED_NAMESPACE = "7e2f4b9a-3c1d-4a68-8d05-b6c9e1f27a34";
 /**
  * Deterministic aggregate-id für die subscription eines Plattform-
  * Tenants. EINE Subscription pro Tenant (Add-Ons sind line-items in
@@ -51,3 +54,8 @@ export function paymentRowId(tenantId, providerName, providerEventId) {
     // the payment with no error anywhere.
     return uuidv5(`${tenantId}:${providerName}:${providerEventId}`, PAYMENT_ROW_NAMESPACE);
 }
+/** Stream id of one unmatched termination declaration, derived from its request id. */
+// @wrapper-known uuid-domain
+export function terminationUnmatchedAggregateId(requestId) {
+    return uuidv5(requestId, TERMINATION_UNMATCHED_NAMESPACE);
+}

package/dist/billing-foundation/checkout-core.d.ts

@@ -88,6 +88,9 @@ export type OpenCheckoutInput = {
     readonly cancelUrl: string;
     readonly providerCustomerId?: string;
     readonly mode?: "subscription" | "payment";
+    readonly consentId?: string;
+    readonly locale?: string;
+    readonly submitMessage?: string;
 };
 /** The one checkout entry-point create-checkout-session and
  *  start-plan-checkout both funnel through. `mode: "payment"` (one-off

package/dist/billing-foundation/checkout-core.js

@@ -282,6 +282,9 @@ export async function openCheckout(ctx, options, input) {
         // pre-hardening wire-contract for callers that never sent `mode`
         // (create-checkout-session's own regression pin).
         ...(input.mode && { mode: input.mode }),
+        ...(input.consentId && { consentId: input.consentId }),
+        ...(input.locale && { locale: input.locale }),
+        ...(input.submitMessage && { submitMessage: input.submitMessage }),
     });
     return { url: result.url, providerName: input.providerName };
 }

package/dist/billing-foundation/constants.d.ts

@@ -2,6 +2,12 @@
 import { Temporal as TemporalPolyfill } from "temporal-polyfill";
 export declare const BILLING_FOUNDATION_FEATURE: "billing-foundation";
 export declare const SUBSCRIPTION_PROVIDER_EXTENSION: "subscriptionProvider";
+/** delivery notification type of the § 312f contract confirmation mail. */
+export declare const CONTRACT_CONFIRMATION_NOTIFICATION_TYPE: "billing-foundation:contract-confirmation";
+/** delivery notification types of the § 312k termination receipt and the
+ *  operator notice. */
+export declare const CONTRACT_TERMINATION_RECEIPT_NOTIFICATION_TYPE: "billing-foundation:contract-termination-receipt";
+export declare const CONTRACT_TERMINATION_OPERATOR_NOTIFICATION_TYPE: "billing-foundation:contract-termination-operator-notice";
 export declare const SubscriptionFoundationHandlers: {
     /** Programmatic entry-point für den webhook-handler. Receives the
      *  parsed SubscriptionEvent (vom Plugin schon verifiziert) + macht
@@ -22,6 +28,22 @@ export declare const SubscriptionFoundationHandlers: {
      *  (payment-aggregate), separate from the subscription-aggregate — a
      *  payment is not a subscription-state transition. */
     readonly processPaymentEvent: "billing-foundation:write:process-payment-event";
+    /** System-only: sends the § 312f contract confirmation mail for a recorded
+     *  checkout consent (consumerProtection only). */
+    readonly issueContractConfirmation: "billing-foundation:write:issue-contract-confirmation";
+    /** System-only: records a termination/withdrawal on the tenant's
+     *  subscription stream and asks the provider to cancel (consumerProtection
+     *  only). */
+    readonly recordContractTermination: "billing-foundation:write:record-contract-termination";
+    /** System-only: records a public declaration no single tenant could be
+     *  matched to, on a system-tenant stream (consumerProtection only). */
+    readonly recordUnmatchedContractTermination: "billing-foundation:write:record-unmatched-contract-termination";
+    /** Anonymous § 312k cancellation/withdrawal declaration (consumerProtection
+     *  only). */
+    readonly requestContractTermination: "billing-foundation:write:request-contract-termination";
+    /** Tenant-Admin terminates or withdraws from the contract of their own
+     *  tenant (consumerProtection only). */
+    readonly terminateContract: "billing-foundation:write:terminate-contract";
     /** Tenant-Admin/purchase-role picks a plan tier from the catalog with no
      *  existing non-terminal subscription — starts a hosted checkout for the
      *  matching price. Only registered when `createBillingFoundationFeature`
@@ -47,6 +69,9 @@ export declare const SubscriptionFoundationQueries: {
      *  current tier and per-plan action. Only registered when a `catalog` is
      *  configured. */
     readonly billingPlans: "billing-foundation:query:billing-plans";
+    /** System-only probe: does the caller tenant hold a non-terminal
+     *  subscription (consumerProtection only). */
+    readonly terminableSubscription: "billing-foundation:query:terminable-subscription";
 };
 export declare const SubscriptionEventTypes: {
     readonly created: "subscription.created";
@@ -69,6 +94,12 @@ export declare const BillingEventKinds: {
     readonly payment: "payment";
 };
 export type BillingEventKind = (typeof BillingEventKinds)[keyof typeof BillingEventKinds];
+export declare const SubscriptionCancelTimings: {
+    readonly periodEnd: "period-end";
+    readonly immediately: "immediately";
+};
+export type SubscriptionCancelTiming = (typeof SubscriptionCancelTimings)[keyof typeof SubscriptionCancelTimings];
+export declare function parseProviderConsentId(raw: unknown): string | undefined;
 export declare const BILLING_PLANS_SCREEN_ID: "billing-plans";
 export declare const BILLING_PLANS_PANEL_COMPONENT: "BillingPlansPanel";
 export declare const BillingPlanActions: {

package/dist/billing-foundation/constants.js

@@ -12,6 +12,12 @@ export const BILLING_FOUNDATION_FEATURE = "billing-foundation";
 // Extension-point name fuer Provider-Plugins (subscription-stripe,
 // subscription-mollie, ...).
 export const SUBSCRIPTION_PROVIDER_EXTENSION = "subscriptionProvider";
+/** delivery notification type of the § 312f contract confirmation mail. */
+export const CONTRACT_CONFIRMATION_NOTIFICATION_TYPE = "billing-foundation:contract-confirmation";
+/** delivery notification types of the § 312k termination receipt and the
+ *  operator notice. */
+export const CONTRACT_TERMINATION_RECEIPT_NOTIFICATION_TYPE = "billing-foundation:contract-termination-receipt";
+export const CONTRACT_TERMINATION_OPERATOR_NOTIFICATION_TYPE = "billing-foundation:contract-termination-operator-notice";
 // Qualified write handler names (QN format: scope:type:name).
 export const SubscriptionFoundationHandlers = {
     /** Programmatic entry-point für den webhook-handler. Receives the
@@ -33,6 +39,22 @@ export const SubscriptionFoundationHandlers = {
      *  (payment-aggregate), separate from the subscription-aggregate — a
      *  payment is not a subscription-state transition. */
     processPaymentEvent: "billing-foundation:write:process-payment-event",
+    /** System-only: sends the § 312f contract confirmation mail for a recorded
+     *  checkout consent (consumerProtection only). */
+    issueContractConfirmation: "billing-foundation:write:issue-contract-confirmation",
+    /** System-only: records a termination/withdrawal on the tenant's
+     *  subscription stream and asks the provider to cancel (consumerProtection
+     *  only). */
+    recordContractTermination: "billing-foundation:write:record-contract-termination",
+    /** System-only: records a public declaration no single tenant could be
+     *  matched to, on a system-tenant stream (consumerProtection only). */
+    recordUnmatchedContractTermination: "billing-foundation:write:record-unmatched-contract-termination",
+    /** Anonymous § 312k cancellation/withdrawal declaration (consumerProtection
+     *  only). */
+    requestContractTermination: "billing-foundation:write:request-contract-termination",
+    /** Tenant-Admin terminates or withdraws from the contract of their own
+     *  tenant (consumerProtection only). */
+    terminateContract: "billing-foundation:write:terminate-contract",
     /** Tenant-Admin/purchase-role picks a plan tier from the catalog with no
      *  existing non-terminal subscription — starts a hosted checkout for the
      *  matching price. Only registered when `createBillingFoundationFeature`
@@ -59,6 +81,9 @@ export const SubscriptionFoundationQueries = {
      *  current tier and per-plan action. Only registered when a `catalog` is
      *  configured. */
     billingPlans: "billing-foundation:query:billing-plans",
+    /** System-only probe: does the caller tenant hold a non-terminal
+     *  subscription (consumerProtection only). */
+    terminableSubscription: "billing-foundation:query:terminable-subscription",
 };
 // Normalized subscription-event types — provider-agnostic.
 // Alle Provider-Plugins normalisieren ihre eigenen event-types auf einen
@@ -90,6 +115,16 @@ export const BillingEventKinds = {
     subscription: "subscription",
     payment: "payment",
 };
+export const SubscriptionCancelTimings = {
+    periodEnd: "period-end",
+    immediately: "immediately",
+};
+// consentId is echoed back by the provider (checkout metadata), so it is
+// untrusted input: bounded length, id-ish charset only.
+const CONSENT_ID_PATTERN = /^[A-Za-z0-9_-]{1,100}$/;
+export function parseProviderConsentId(raw) {
+    return typeof raw === "string" && CONSENT_ID_PATTERN.test(raw) ? raw : undefined;
+}
 // Billing-plans screen/panel identifiers — the dormant dashboard app-builders
 // mount their own catalog-derived nav entry onto.
 export const BILLING_PLANS_SCREEN_ID = "billing-plans";

package/dist/billing-foundation/consumer-protection/confirmation-mail.d.ts

@@ -0,0 +1,21 @@
+import type { CheckoutConsentRecordedPayload } from "../events.js";
+export type ContractConfirmationContent = {
+    readonly subject: string;
+    readonly header: string;
+    readonly sections: readonly {
+        readonly text: string;
+    }[];
+    readonly footer: string;
+};
+export type RenderContractConfirmationArgs = {
+    readonly consent: CheckoutConsentRecordedPayload;
+    readonly consentGivenAtIso: string;
+    readonly contractStartIso: string;
+    readonly currentPeriodEndIso?: string;
+    readonly vatNote: Readonly<Record<string, string>>;
+    readonly operatorEmail: string;
+    readonly termsContent: string;
+};
+/** Structured mail content (header/sections/footer) for the email channel's
+ *  renderer; the renderer owns HTML escaping, this only builds plain text. */
+export declare function renderContractConfirmation(args: RenderContractConfirmationArgs): ContractConfirmationContent;