@hadoku/service-kernel 0.0.0-stage → 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hadoku-cardtable contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/auth/index.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Edge provenance and the tier floor — the platform's half.
+ *
+ * An edge-router style gateway resolves a caller's tier once and stamps every
+ * request it proxies with a shared-secret header plus tier / user-id /
+ * user-key / user-name / verified headers. A game's own tunnel host is
+ * reachable DIRECTLY, bypassing that edge — so a direct hit could forge those
+ * headers. We believe them only when the shared secret checks out; otherwise
+ * we overwrite them with the most restrictive identity.
+ *
+ * Overwriting rather than deleting is deliberate: a handler that treats an
+ * ABSENT tier as "bare local, trust it" would hand a direct caller the keys.
+ * An explicit `public` cannot be read that way.
+ *
+ * Knows no game: every value below is either a pure header read or injected
+ * by the app that binds this module (its edge-auth secret, its bare-local
+ * dev hatch, its dev tier).
+ */
+import type { IncomingHttpHeaders } from 'node:http';
+import type { NextFunction, Request, Response } from 'express';
+/**
+ * The platform tier ladder, complete. `wife` sits above `service` and below
+ * `admin` deliberately: full reach across the apps, none of the
+ * credential-management surface. `member` is a self-signed-up account: a
+ * passkey and a name, no key anyone handed out.
+ */
+export declare const TIER_ORDER: readonly ["public", "member", "friend", "service", "wife", "admin"];
+export type Tier = (typeof TIER_ORDER)[number];
+export interface AssertFloorOptions {
+    /** Named in the refusal message, e.g. `CARDTABLE` for `CARDTABLE_MIN_TIER=…`. */
+    envPrefix: string;
+    /**
+     * Let the app choose `public` as its own floor. Off by default: a floor an
+     * app never meant to be public should refuse to boot rather than silently
+     * admit everyone. Apps that are genuinely public (the next game might be)
+     * opt in explicitly.
+     */
+    allowPublic?: boolean;
+}
+/**
+ * The floor must be a tier this build knows. An unknown name ranks as public
+ * in {@link rankOf}, so a floor this build has not heard of would silently
+ * admit everyone, the direct tunnel hits included. Refusing to boot is the
+ * only safe answer — and, unless the app opts in, `public` itself is refused
+ * the same way, since an app that calls this at all is declaring it wants a
+ * gate.
+ */
+export declare function assertFloor(tier: string, opts: AssertFloorOptions): Tier;
+export declare function rankOf(tier: string): number;
+/**
+ * The app's own edge-auth binding: its shared secret and its bare-local dev
+ * hatch. Read live (as functions, not snapshotted values) so an app that
+ * flips these at runtime — tests do — sees the new value on the very next
+ * call, exactly as the single-process `CONFIG` object this used to read
+ * directly always did.
+ */
+export interface EdgeAuthConfig {
+    /** The shared secret this build believes `X-Edge-Auth` against. `''` = fail closed. */
+    edgeAuthSecret(): string;
+    /** The bare-local escape hatch: believe whatever tier a header-less caller claims. */
+    allowUnverifiedEdge(): boolean;
+    /** The tier granted a header-less caller while the hatch above is open. */
+    devTier(): string;
+}
+export interface EdgeAuth {
+    /** Force a public/anon identity unless edge provenance is proven. */
+    sanitizeHeaders(headers: Record<string, unknown>): void;
+    /**
+     * Did this request carry the edge's own seal? Not the bare-local hatch,
+     * which believes any header: a route only the edge may call asks this
+     * rather than a tier.
+     */
+    edgeSealed(req: Request): boolean;
+    /** Express middleware: sanitize provenance on every inbound request. */
+    edgeProvenance(req: Request, res: Response, next: NextFunction): void;
+}
+/** Build the three functions that need the app's own edge-auth secret and dev hatch. */
+export declare function createEdgeAuth(config: EdgeAuthConfig): EdgeAuth;
+/**
+ * The caller's tier as the app's headers carry it, except that a verified
+ * member IS a friend here: an app that admits members alongside the tiers it
+ * hands out may choose to treat its own verification the same as a vouch.
+ * Never above friend: admin stays admin's. Pure — only `sanitizeHeaders`
+ * decides whether a header is trustworthy in the first place.
+ */
+export declare function tierOf(req: Request): string;
+/**
+ * Is this caller verified (`X-Hadoku-Verified: 1`)? Absent means not
+ * verified. Pure: trustworthiness is `sanitizeHeaders`'s job, done before this
+ * is ever read.
+ */
+export declare function verifiedOf(req: Request): boolean;
+/** `verifiedOf` for a socket's handshake, whose headers went through the same sanitizing. */
+export declare function verifiedFromHeaders(headers: IncomingHttpHeaders): boolean;
+/** The caller's userId as the edge stamped it; null when the edge named nobody. */
+export declare function callerIdOf(req: Request): string | null;
+export declare function userIdOf(req: Request): string;
+/**
+ * The caller's own live key (`X-User-Key`), edge-stamped and stripped from an
+ * unvouched request. A credential: never log it or store it. null when the
+ * edge sent none.
+ */
+export declare function userKeyOf(req: Request): string | null;
+/**
+ * The caller's registry userId (`X-User-Id`), edge-stamped and stripped from
+ * an unvouched request. null when the edge sent none, never a stand-in word.
+ */
+export declare function accountIdOf(req: Request): string | null;
+/**
+ * The caller's DISPLAY NAME, edge-injected beside `X-User-Id` (same trust
+ * class: exclusively edge-set, stripped from unvouched requests). null when
+ * the edge sent none — an unnamed key.
+ */
+export declare function userNameOf(req: Request): string | null;
+/** `userNameOf` for a socket's handshake, whose headers went through the same sanitizing. */
+export declare function userNameFromHeaders(headers: IncomingHttpHeaders): string | null;
+/**
+ * A header value as the text its sender meant. The edge sends a name's UTF-8
+ * bytes and Node reads every header byte as one Latin-1 character, so
+ * `王蟲様` arrives as `ç\x8e\x8bè…`. Bytes that are valid UTF-8 are read as
+ * UTF-8; anything else (plain ASCII, or a lone Latin-1 byte) is kept as it came.
+ */
+export declare function utf8HeaderValue(value: string): string;
+/** The one admin check: `rankOf(tierOf(req)) >= rankOf('admin')`. */
+export declare function isAdmin(req: Request): boolean;

package/dist/auth/index.js

@@ -0,0 +1,189 @@
+/**
+ * Edge provenance and the tier floor — the platform's half.
+ *
+ * An edge-router style gateway resolves a caller's tier once and stamps every
+ * request it proxies with a shared-secret header plus tier / user-id /
+ * user-key / user-name / verified headers. A game's own tunnel host is
+ * reachable DIRECTLY, bypassing that edge — so a direct hit could forge those
+ * headers. We believe them only when the shared secret checks out; otherwise
+ * we overwrite them with the most restrictive identity.
+ *
+ * Overwriting rather than deleting is deliberate: a handler that treats an
+ * ABSENT tier as "bare local, trust it" would hand a direct caller the keys.
+ * An explicit `public` cannot be read that way.
+ *
+ * Knows no game: every value below is either a pure header read or injected
+ * by the app that binds this module (its edge-auth secret, its bare-local
+ * dev hatch, its dev tier).
+ */
+/**
+ * The platform tier ladder, complete. `wife` sits above `service` and below
+ * `admin` deliberately: full reach across the apps, none of the
+ * credential-management surface. `member` is a self-signed-up account: a
+ * passkey and a name, no key anyone handed out.
+ */
+export const TIER_ORDER = ['public', 'member', 'friend', 'service', 'wife', 'admin'];
+/**
+ * The floor must be a tier this build knows. An unknown name ranks as public
+ * in {@link rankOf}, so a floor this build has not heard of would silently
+ * admit everyone, the direct tunnel hits included. Refusing to boot is the
+ * only safe answer — and, unless the app opts in, `public` itself is refused
+ * the same way, since an app that calls this at all is declaring it wants a
+ * gate.
+ */
+export function assertFloor(tier, opts) {
+    const allowPublic = opts.allowPublic ?? false;
+    if (!TIER_ORDER.includes(tier) || (!allowPublic && tier === 'public')) {
+        throw new Error(`${opts.envPrefix}_MIN_TIER=${tier} is not a tier floor this build knows`);
+    }
+    return tier;
+}
+export function rankOf(tier) {
+    const i = TIER_ORDER.indexOf(tier);
+    // An unknown tier is not a high one. A future tier name this build has never
+    // heard of must not out-rank the floor by accident.
+    return i === -1 ? 0 : i;
+}
+/** Constant-time compare. Length is not secret (the token is fixed-length). */
+function ctEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/** Build the three functions that need the app's own edge-auth secret and dev hatch. */
+export function createEdgeAuth(config) {
+    function edgeProvenanceOk(headers) {
+        const got = headers['x-edge-auth'];
+        const secret = config.edgeAuthSecret();
+        return secret !== '' && typeof got === 'string' && ctEqual(got, secret);
+    }
+    function sanitizeHeaders(headers) {
+        if (config.edgeAuthSecret() === '') {
+            if (config.allowUnverifiedEdge()) {
+                // Explicit bare-local opt-out (warned at boot). Believe whatever tier
+                // the caller claims — and, when it claims none, GRANT the dev tier
+                // rather than leaving the header absent.
+                //
+                // That second half is the whole point. Without it the escape hatch does
+                // not open anything: a browser at localhost sends no X-Hadoku-Tier, so
+                // the floor below reads it as `public` and 404s every route including
+                // the app's own index.html. The hatch would be a flag that changes
+                // nothing observable, which is worse than not having one.
+                if (typeof headers['x-hadoku-tier'] !== 'string' || headers['x-hadoku-tier'] === '') {
+                    headers['x-hadoku-tier'] = config.devTier();
+                    headers['x-user-id'] ??= 'local-dev';
+                    headers['x-user-name'] ??= 'local-dev';
+                }
+                return;
+            }
+            // else fall through: nothing can prove provenance → degrade every request
+        }
+        else if (edgeProvenanceOk(headers)) {
+            return;
+        }
+        headers['x-hadoku-tier'] = 'public';
+        // Content visibility is stamped by the edge from the user's prefs row, so it
+        // is exactly as forgeable as the tier and gets pinned the same way. Level 1
+        // is the platform's SFW floor.
+        headers['x-hadoku-content-level'] = '1';
+        delete headers['x-user-id'];
+        delete headers['x-user-name'];
+        delete headers['x-user-key'];
+        delete headers['x-hadoku-verified'];
+    }
+    function edgeSealed(req) {
+        return edgeProvenanceOk(req.headers);
+    }
+    function edgeProvenance(req, _res, next) {
+        sanitizeHeaders(req.headers);
+        next();
+    }
+    return { sanitizeHeaders, edgeSealed, edgeProvenance };
+}
+/**
+ * The caller's tier as the app's headers carry it, except that a verified
+ * member IS a friend here: an app that admits members alongside the tiers it
+ * hands out may choose to treat its own verification the same as a vouch.
+ * Never above friend: admin stays admin's. Pure — only `sanitizeHeaders`
+ * decides whether a header is trustworthy in the first place.
+ */
+export function tierOf(req) {
+    const t = req.headers['x-hadoku-tier'];
+    const tier = typeof t === 'string' && t !== '' ? t : 'public';
+    return tier === 'member' && verifiedOf(req) ? 'friend' : tier;
+}
+/**
+ * Is this caller verified (`X-Hadoku-Verified: 1`)? Absent means not
+ * verified. Pure: trustworthiness is `sanitizeHeaders`'s job, done before this
+ * is ever read.
+ */
+export function verifiedOf(req) {
+    return verifiedFromHeaders(req.headers);
+}
+/** `verifiedOf` for a socket's handshake, whose headers went through the same sanitizing. */
+export function verifiedFromHeaders(headers) {
+    return headers['x-hadoku-verified'] === '1';
+}
+/** The caller's userId as the edge stamped it; null when the edge named nobody. */
+export function callerIdOf(req) {
+    const u = req.headers['x-user-id'];
+    return typeof u === 'string' && u !== '' ? u : null;
+}
+export function userIdOf(req) {
+    return callerIdOf(req) ?? 'anon';
+}
+/**
+ * The caller's own live key (`X-User-Key`), edge-stamped and stripped from an
+ * unvouched request. A credential: never log it or store it. null when the
+ * edge sent none.
+ */
+export function userKeyOf(req) {
+    const k = req.headers['x-user-key'];
+    return typeof k === 'string' && k !== '' ? k : null;
+}
+/**
+ * The caller's registry userId (`X-User-Id`), edge-stamped and stripped from
+ * an unvouched request. null when the edge sent none, never a stand-in word.
+ */
+export function accountIdOf(req) {
+    const u = req.headers['x-user-id'];
+    return typeof u === 'string' && u !== '' ? u : null;
+}
+/**
+ * The caller's DISPLAY NAME, edge-injected beside `X-User-Id` (same trust
+ * class: exclusively edge-set, stripped from unvouched requests). null when
+ * the edge sent none — an unnamed key.
+ */
+export function userNameOf(req) {
+    return userNameFromHeaders(req.headers);
+}
+/** `userNameOf` for a socket's handshake, whose headers went through the same sanitizing. */
+export function userNameFromHeaders(headers) {
+    const n = headers['x-user-name'];
+    return typeof n === 'string' && n !== '' ? utf8HeaderValue(n) : null;
+}
+const STRICT_UTF8 = new TextDecoder('utf-8', { fatal: true });
+/**
+ * A header value as the text its sender meant. The edge sends a name's UTF-8
+ * bytes and Node reads every header byte as one Latin-1 character, so
+ * `王蟲様` arrives as `ç\x8e\x8bè…`. Bytes that are valid UTF-8 are read as
+ * UTF-8; anything else (plain ASCII, or a lone Latin-1 byte) is kept as it came.
+ */
+export function utf8HeaderValue(value) {
+    const codes = Array.from(value, (c) => c.charCodeAt(0));
+    if (!codes.some((c) => c >= 0x80) || codes.some((c) => c > 0xff))
+        return value;
+    try {
+        return STRICT_UTF8.decode(Buffer.from(value, 'latin1'));
+    }
+    catch {
+        return value;
+    }
+}
+/** The one admin check: `rankOf(tierOf(req)) >= rankOf('admin')`. */
+export function isAdmin(req) {
+    return rankOf(tierOf(req)) >= rankOf('admin');
+}

package/dist/capacity/capacity.d.ts

@@ -0,0 +1,33 @@
+import type { NextFunction, Request, Response } from 'express';
+import { type Report } from '../telemetry/telemetry.js';
+export declare const CAPACITY_WINDOW_MS: number;
+export declare const SAMPLE_MS = 15000;
+export type Gauges = Record<string, () => number>;
+export interface CapacityDeps {
+    gauges: Gauges;
+    report?: Report;
+    now?: () => number;
+    windowMs?: number;
+    sampleMs?: number;
+    /** Counts for the window, read once as each post goes out; the reader resets its own. */
+    counts?: () => Record<string, unknown>;
+    /** Process memory; `process.memoryUsage` in production. */
+    memory?: () => {
+        rss: number;
+        heapUsed: number;
+    };
+    /** A request path counted on its own, under `uncountedField`, never timed. Default: none. */
+    uncountedPath?: (path: string) => boolean;
+    /** The capacity event's field for `uncountedPath`'s count. Default: `'uncounted'`. */
+    uncountedField?: string;
+}
+export interface CapacitySampler {
+    /** Express middleware: counts each finished request and its duration. */
+    requests: (req: Request, res: Response, next: NextFunction) => void;
+    /** Begin sampling. Called once the server listens: the gauges read what boot builds. */
+    start(): void;
+    sample(): void;
+    flush(): void;
+    stop(): void;
+}
+export declare function capacitySampler(deps: CapacityDeps): CapacitySampler;

package/dist/capacity/capacity.js

@@ -0,0 +1,119 @@
+/**
+ * What load this server carried, and how close it came to a ceiling: sampled every `SAMPLE_MS`,
+ * posted to telemetry as one `capacity` event per window with each gauge's peak and the request
+ * rate and latency. Read beside the edge's request log, it says how much traffic a given amount
+ * of headroom absorbed — the evidence for "how many players can this take".
+ *
+ * Gauges are callbacks so this file knows nothing of sockets, rooms or Forge: the app hands them
+ * in, and nothing is read before `start()`. The event loop's delay is measured here
+ * (`monitorEventLoopDelay`), because a server whose loop stalls is out of capacity whatever its
+ * gauges say.
+ *
+ * One request path is counted on its own, never timed: `uncountedPath`, under
+ * `uncountedField` in the posted event. A page that asks for ~120 images at once would otherwise
+ * swamp the request rate and pull p95 down to nothing; which path that is (cardtable's card art)
+ * and what the field is called are the app's own choice, not this module's.
+ */
+import { monitorEventLoopDelay } from 'node:perf_hooks';
+import { report as defaultReport } from "../telemetry/telemetry.js";
+export const CAPACITY_WINDOW_MS = 5 * 60_000;
+export const SAMPLE_MS = 15_000;
+const MB = 1024 * 1024;
+export function capacitySampler(deps) {
+    const report = deps.report ?? defaultReport;
+    const now = deps.now ?? Date.now;
+    const memory = deps.memory ?? (() => process.memoryUsage());
+    const uncountedPath = deps.uncountedPath ?? (() => false);
+    const uncountedField = deps.uncountedField ?? 'uncounted';
+    const loop = monitorEventLoopDelay({ resolution: 20 });
+    loop.enable();
+    let windowStart = now();
+    let peaks = {};
+    let last = {};
+    let samples = 0;
+    let durations = [];
+    let errors = 0;
+    /** Requests matching `uncountedPath`: counted, never timed. */
+    let uncounted = 0;
+    const sample = () => {
+        samples += 1;
+        const m = memory();
+        const reading = {
+            ...Object.fromEntries(Object.entries(deps.gauges).map(([k, read]) => [k, read()])),
+            rssMb: Math.round(m.rss / MB),
+            heapMb: Math.round(m.heapUsed / MB),
+        };
+        for (const [k, v] of Object.entries(reading))
+            peaks[k] = Math.max(peaks[k] ?? v, v);
+        last = reading;
+    };
+    const flush = () => {
+        const start = windowStart;
+        windowStart = now();
+        const seconds = Math.max(1, (windowStart - start) / 1000);
+        const sorted = [...durations].sort((a, b) => a - b);
+        const pct = (p) => sorted.length === 0 ? null : sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))];
+        const context = {
+            from: new Date(start).toISOString(),
+            minutes: Math.round(seconds / 60),
+            samples,
+            peak: peaks,
+            now: last,
+            requests: sorted.length,
+            perMin: Math.round((sorted.length / seconds) * 60),
+            p50Ms: pct(0.5),
+            p95Ms: pct(0.95),
+            maxMs: sorted.at(-1) ?? null,
+            errors5xx: errors,
+            loopP99Ms: Math.round(loop.percentile(99) / 1e6),
+            loopMaxMs: Math.round(loop.max / 1e6),
+        };
+        context[uncountedField] = uncounted;
+        Object.assign(context, deps.counts?.());
+        report('capacity', context);
+        peaks = {};
+        samples = 0;
+        durations = [];
+        errors = 0;
+        uncounted = 0;
+        loop.reset();
+    };
+    let timers = [];
+    return {
+        requests: (req, res, next) => {
+            if (uncountedPath(req.path)) {
+                uncounted += 1;
+                next();
+                return;
+            }
+            const t = process.hrtime.bigint();
+            res.on('finish', () => {
+                durations.push(Number(process.hrtime.bigint() - t) / 1e6);
+                if (res.statusCode >= 500)
+                    errors += 1;
+            });
+            next();
+        },
+        start: () => {
+            if (timers.length > 0)
+                return;
+            windowStart = now();
+            durations = [];
+            loop.reset();
+            timers = [
+                setInterval(sample, deps.sampleMs ?? SAMPLE_MS),
+                setInterval(flush, deps.windowMs ?? CAPACITY_WINDOW_MS),
+            ];
+            for (const t of timers)
+                t.unref();
+        },
+        sample,
+        flush,
+        stop: () => {
+            for (const t of timers)
+                clearInterval(t);
+            timers = [];
+            loop.disable();
+        },
+    };
+}

package/dist/capacity/index.d.ts

@@ -0,0 +1 @@
+export { CAPACITY_WINDOW_MS, SAMPLE_MS, capacitySampler, type CapacityDeps, type CapacitySampler, type Gauges, } from './capacity.js';

package/dist/capacity/index.js

@@ -0,0 +1 @@
+export { CAPACITY_WINDOW_MS, SAMPLE_MS, capacitySampler, } from "./capacity.js";

package/dist/erase/anonymise.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Anonymising a shared record (account erase, `index.ts`): a room, a pod, a tournament or an
+ * event that other players own too keeps its shape, and the erased person in it becomes a
+ * placeholder id nobody can be traced back to.
+ *
+ * One mechanism for every store, so a store's erase is "which object to walk"
+ * and never a list of the fields that happen to hold an id today: a field added
+ * tomorrow is covered without anyone remembering this file.
+ */
+/** The id an erased person becomes: fresh per erase, so two erased people never merge into one. */
+export declare function placeholderId(): string;
+/**
+ * Replace every string in `ids` with `to`, in place, wherever it sits in `value`: a string
+ * value, an array element, an object key, a Map key or value, a Set member. Functions are
+ * left alone, an object reached twice is walked once, and nothing is written that does not
+ * change (a record may share a frozen constant). Answers how many it replaced.
+ */
+export declare function replaceIds(value: unknown, ids: ReadonlySet<string>, to: string): number;

package/dist/erase/anonymise.js

@@ -0,0 +1,77 @@
+/**
+ * Anonymising a shared record (account erase, `index.ts`): a room, a pod, a tournament or an
+ * event that other players own too keeps its shape, and the erased person in it becomes a
+ * placeholder id nobody can be traced back to.
+ *
+ * One mechanism for every store, so a store's erase is "which object to walk"
+ * and never a list of the fields that happen to hold an id today: a field added
+ * tomorrow is covered without anyone remembering this file.
+ */
+import { randomBytes } from 'node:crypto';
+/** The id an erased person becomes: fresh per erase, so two erased people never merge into one. */
+export function placeholderId() {
+    return `erased:${randomBytes(4).toString('hex')}`;
+}
+/**
+ * Replace every string in `ids` with `to`, in place, wherever it sits in `value`: a string
+ * value, an array element, an object key, a Map key or value, a Set member. Functions are
+ * left alone, an object reached twice is walked once, and nothing is written that does not
+ * change (a record may share a frozen constant). Answers how many it replaced.
+ */
+export function replaceIds(value, ids, to) {
+    const seen = new WeakSet();
+    const swap = (v) => (typeof v === 'string' && ids.has(v) ? { v: to, n: 1 } : { v, n: walk(v) });
+    function walk(node) {
+        if (node === null || typeof node !== 'object' || seen.has(node))
+            return 0;
+        seen.add(node);
+        let n = 0;
+        if (Array.isArray(node)) {
+            for (let i = 0; i < node.length; i++) {
+                const r = swap(node[i]);
+                if (r.v !== node[i])
+                    node[i] = r.v;
+                n += r.n;
+            }
+        }
+        else if (node instanceof Map) {
+            for (const [k, v] of [...node]) {
+                const key = swap(k);
+                const val = swap(v);
+                if (key.v !== k)
+                    node.delete(k);
+                if (key.v !== k || val.v !== v)
+                    node.set(key.v, val.v);
+                n += key.n + val.n;
+            }
+        }
+        else if (node instanceof Set) {
+            for (const m of [...node]) {
+                const r = swap(m);
+                if (r.v !== m) {
+                    node.delete(m);
+                    node.add(r.v);
+                }
+                n += r.n;
+            }
+        }
+        else {
+            const record = node;
+            for (const k of Object.keys(record)) {
+                const val = swap(record[k]);
+                if (ids.has(k)) {
+                    delete record[k];
+                    record[to] = val.v;
+                    n += 1 + val.n;
+                }
+                else {
+                    if (val.v !== record[k])
+                        record[k] = val.v;
+                    n += val.n;
+                }
+            }
+        }
+        return n;
+    }
+    return walk(value);
+}

package/dist/erase/erase.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Account deletion's erase hook (hadoku_site IDENTITY_MODEL R12, "Erase hooks"; the caller is
+ * edge-router's `eraseMemberData`, which runs it on account delete and on the merged-away side of
+ * an account merge).
+ *
+ * The edge calls it with its own seal and `X-User-Id`, and wants 200 `{ erased: { <what>: <count> } }`
+ * back, zeros on a second call. Anything else fails the whole delete, which the edge retries, so a
+ * step that throws answers 500 rather than a partial count.
+ *
+ * Only the seal admits it — `edgeSealed` is an injected check, never a tier: this module knows no
+ * app's edge-auth binding. `deriveParticipantId` is likewise injected: the id a person is also
+ * known by (the `fk:`/`dev:`/`eph:` scheme, whichever app provides it) is platform but app-bound,
+ * not this kernel's to import.
+ *
+ * What is erased is a list of steps each store registers where it is built (`register`), so a
+ * store and its erase live side by side in the app. Steps run one at a time, in registration
+ * order, so two never rewrite one file at once.
+ */
+import type { Request, Response } from 'express';
+/** `/api/_account/erase` — the one path every app answers this hook on. */
+export declare const ERASE_PATH = "/api/_account/erase";
+/** Whom one erase is for. */
+export interface ErasedPerson {
+    /** The registry userId, as the edge sent it. */
+    userId: string;
+    /** The app's own id for this person (its identity scheme's derived id). */
+    participantId: string;
+    /** Both of the above: what a shared record names them by (`replaceIds`). */
+    ids: ReadonlySet<string>;
+    /** What they become in a shared record, one per erase (`placeholderId`). */
+    placeholder: string;
+}
+/**
+ * One store's part of an erase: how many of the person's records it erased or anonymised,
+ * zero when none are left. A store with several kinds of record answers a count for each,
+ * by name, and `what` only names the step.
+ */
+export type EraseCounts = number | Record<string, number>;
+export interface EraseStep {
+    what: string;
+    erase(person: ErasedPerson): EraseCounts | Promise<EraseCounts>;
+}
+export interface AccountErase {
+    /** Add a store's step. A second step under one name is a wiring bug and throws. */
+    register(step: EraseStep): void;
+    /** Run every step for this userId. Throws the first step's failure. */
+    erase(userId: string): Promise<Record<string, number>>;
+    /** The route's handler. */
+    handle(req: Request, res: Response): Promise<void>;
+}
+export interface AccountEraseOptions {
+    log: (entry: Record<string, unknown>) => void;
+    /** Did this request carry the edge's own seal? Never a tier check. */
+    edgeSealed: (req: Request) => boolean;
+    /** This app's own identity scheme's derived id for a registry userId. */
+    deriveParticipantId: (userId: string) => string;
+}
+export declare function personOf(userId: string, deriveParticipantId: (userId: string) => string): ErasedPerson;
+export declare function createAccountErase(opts: AccountEraseOptions): AccountErase;