@amalgm/core 0.1.0

package/PURPOSE.md

@@ -0,0 +1,94 @@
+# @amalgm/core
+
+## Purpose
+
+`@amalgm/core` is the Amalgm kernel: the smallest set of contracts and
+decision logic a machine needs to **boot** the platform, **prove who it is**,
+**stay alive**, and **route traffic to everything else**. Every product —
+live, chat, automations, apps, agents, toolbox, channels — rides on core;
+core depends on none of them.
+
+The membership test for this repository is one sentence: **if it is needed to
+boot, supervise, or route to an app, and it cannot itself be an app, it is
+core. Everything else is not.**
+
+Core owns exactly four things:
+
+1. **Identity** — who this machine is, for which user, on which branch.
+   The `~/.amalgm/<user>/<branch>/` layout, machine/instance identity,
+   auth-store contracts, and the branch-binding rule surfaces use to decide
+   whether they may attach.
+2. **Transport** — the pipe. The local gateway's routing and admission
+   rules, the tunnel connection contract, and the event rail. The pipe
+   carries payloads it never interprets: sync semantics belong to
+   `@amalgm/live`, chat semantics to `@amalgm/chat`. (SIM card, not
+   FaceTime.)
+3. **Supervision** — the cascade that keeps everything running: launchd →
+   CLI parent → runtime → app supervisor, health contracts, restart policy,
+   and the updater.
+4. **Host capabilities** — the narrow, named powers a host grants
+   (spawn a service, write a plist, open a port), expressed as adapter
+   ports, never reached for directly.
+
+`docs/responsibilities.md` enumerates every responsibility in full and maps
+each engine module to its target repo. This repository is where the kernel's
+rules become executable and testable; the engine repo remains the production
+source until each module is cut over.
+
+## Axioms
+
+1. **Core is the floor, not the building.** Nothing product-shaped lives
+   here — no chat, no documents, no automations, no tools. A feature that
+   could be an app is a bug in core.
+2. **Identity is one story.** User, machine, branch — resolved once, by one
+   rule set, and every path, socket, and token scope derives from it. A
+   second place that computes a home directory or a branch match is a bug.
+3. **The pipe never reads the mail.** Transport moves opaque payloads
+   between named endpoints. A routing rule that inspects payload semantics
+   belongs to the product that owns the payload.
+4. **One routing table.** Gateway, tunnel, and runtime consult one
+   definition of prefixes, ports, and admission. The engine's three drifted
+   copies are the wound this axiom closes.
+5. **Supervision flows one way.** launchd supervises the parent, the parent
+   supervises the runtime, the runtime supervises apps. A child never
+   restarts its parent, and each layer reports its children's health
+   honestly — `degraded` and `unresponsive` are states, not failures to
+   hide.
+6. **A host supplies its own effects.** The SDK receives process,
+   filesystem, clock, network, and crypto adapters. Nothing in `src/` may
+   import `node:fs`, `node:net`, `node:child_process`, or read an
+   environment variable.
+7. **Protocol evolution is additive only.** Every peer treats missing
+   fields and unknown frames as "the other end is older" and keeps the
+   legacy behavior. A change that breaks a deployed peer is rejected in
+   review.
+8. **Contracts are byte-exact.** Path formats, plist labels, health
+   vocabularies, error strings, and version-compare rules are preserved
+   verbatim from the shipped engine; parity tests pin them until cutover.
+9. **The current runtime remains the single production source until moved.**
+   This package extracts contracts and decision logic with their tests; it
+   does not create a parallel execution path. The engine adopts it module by
+   module, deleting its duplicated copy in the same change.
+10. **Amalgm's own surfaces use this SDK.** A private shortcut in the CLI,
+    gateway, or runtime means the SDK is incomplete — fix the SDK, not the
+    caller.
+
+## Five surfaces, one behavior
+
+```
+src/            the SDK — the behavior. Contracts + decision cores + ports.
+surfaces/api    REST router factory a host mounts (identity/health/routing).
+surfaces/cli    `amalgm-core` — resolve layouts, explain routes, check health.
+surfaces/mcp    MCP server exposing the same actions to agents.
+skills/core     the skill: teaches an agent the kernel via the CLI/MCP.
+```
+
+Every surface is a thin adapter over `src/`. A surface that implements
+behavior instead of delegating to the SDK is a bug.
+
+## Status
+
+Charter stage. Inventory of the engine's kernel territory is in
+`docs/responsibilities.md`; extraction proceeds pure-cores-first, exactly as
+`@amalgm/live` was built. The engine runtime and CLI remain the production
+source; nothing consumes this package yet.

package/README.md

@@ -0,0 +1,30 @@
+# @amalgm/core
+
+The Amalgm kernel SDK: identity, transport, and supervision contracts —
+every law a machine needs to boot the platform, prove who it is, stay
+alive, and route traffic to everything else. Start with
+[PURPOSE.md](PURPOSE.md) (the charter) and
+[docs/responsibilities.md](docs/responsibilities.md) (every duty, and the
+knife table mapping the engine monolith onto its target repos).
+
+```
+src/identity/     labels, layout grammar, ids, auth records
+src/transport/    the auth boundary, ONE routing table, admission, ingress
+src/supervision/  health contracts, restart machines, updater laws,
+                  service registration
+src/adapters/     the ports a host injects (clock, hash, random, hmac…)
+surfaces/         cli · api · mcp — thin doors over src/
+skills/core/      the skill that teaches an agent this kernel
+```
+
+```bash
+npm install
+npm test                      # build + every exam
+node surfaces/cli/amalgm-core.mjs label canary
+```
+
+Rules of the house: zero runtime dependencies; nothing in `src/` imports
+`node:*` or reads `process.env`; contracts are byte-exact against the
+shipped engine (the production source until cutover — PURPOSE.md axiom 9);
+tests are exams — each states a law, and a mutant must be convicted by at
+least one.

package/dist/adapters/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The adapter ports — every real-world effect the kernel SDK needs,
+ * gathered in one place so a host can see the full contract it must
+ * satisfy (PURPOSE.md axiom 6: a host supplies its own effects).
+ *
+ * Nothing in `src/` reaches for `node:*` or `process.env`; these types are
+ * the entire boundary. A Node host wires them from `node:crypto`,
+ * `node:path`, and `Date`; a test wires them from fixtures.
+ */
+export type { ClockIsoPort, ClockMsPort, RandomHexPort, Sha256HexPort, ResolvePathPort, } from '../identity/ports.js';
+export type { TimingSafeEqualPort } from '../transport/auth.js';
+export type { HmacHexPort } from '../transport/ingress.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,YAAY,EACV,YAAY,EACZ,WAAW,EACX,aAAa,EACb,aAAa,EACb,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,YAAY,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/adapters/index.js

@@ -0,0 +1,11 @@
+/**
+ * The adapter ports — every real-world effect the kernel SDK needs,
+ * gathered in one place so a host can see the full contract it must
+ * satisfy (PURPOSE.md axiom 6: a host supplies its own effects).
+ *
+ * Nothing in `src/` reaches for `node:*` or `process.env`; these types are
+ * the entire boundary. A Node host wires them from `node:crypto`,
+ * `node:path`, and `Date`; a test wires them from fixtures.
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/identity/auth-records.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Credential-record shaping laws (engine packages/amalgm/lib/auth-store.js
+ * and runtime/scripts/proxy-token-store.js) — how a computer record splits
+ * into its PUBLIC face (`computer.json`) and its SECRET envelope
+ * (`auth.json`), how the two merge back, and when a proxy token counts as
+ * fresh. Pure record computations only: reading, writing, and env access
+ * stay host-side; the clock arrives as a port.
+ *
+ * Records are loose JSON from disk, so inputs are typed as they truly are:
+ * dictionaries of unknowns, validated key by key.
+ */
+import type { ClockIsoPort, ClockMsPort } from './ports.js';
+type Dict = Record<string, unknown>;
+/** Emails compare lowercased; a record's email is stored lowercased. */
+export declare function normalizeUserEmail(value: unknown): string;
+/** A record's email under any of its historical spellings (auth-store.js:74-76). */
+export declare function userEmailFromRecord(record: unknown): string;
+/**
+ * Every key that must NEVER appear in the public `computer.json`
+ * (auth-store.js:24-35). Secrets live only in `auth.json`; the exact list —
+ * including the legacy camelCase and hmac spellings — is the contract.
+ */
+export declare const SECRET_COMPUTER_KEYS: ReadonlySet<string>;
+/** Does this record carry any secret worth an auth envelope?
+ * (auth-store.js:78-81). Whitespace-only values do not count. */
+export declare function hasComputerSecrets(record: unknown): boolean;
+/**
+ * The public face of a computer record (auth-store.js:83-92): the record
+ * with every secret key removed, its email normalized, and an `auth_file`
+ * pointer naming the sibling envelope by BASENAME — the record must stay
+ * true when the directory moves. DELIBERATE DEVIATION: the engine's
+ * parameter is a full path passed through `node:path.basename`; the same
+ * basename law is implemented here inline to stay dependency-free.
+ */
+export declare function publicComputerRecord(record: unknown, authFile?: string): Dict;
+/**
+ * The full secret envelope distilled from a computer record
+ * (auth-store.js:94-156):
+ *
+ *   { schema_version: 1, computer_id, device_id, user_id, user_email,
+ *     app_url, tunnel: { token, url, chat_tunnel_url }, machine: { token },
+ *     proxy: { token, expires_in, expires_at, refreshed_at } }
+ *
+ * Merging over `existing` is additive: identity keys are copied only when
+ * the record actually carries them, each token section is (re)stamped only
+ * when its token arrives, and a record carrying only tunnel URLs updates
+ * the URLs while PRESERVING the existing tunnel token. `expires_in`
+ * collapses to undefined (dropped by JSON) when absent or zero. Legacy
+ * proxy-token spellings (proxyToken, hmac_token, hmacToken) are honored on
+ * input; the envelope speaks only the canonical shape.
+ */
+export declare function authFromRecord(record: unknown, existing: unknown, ports: ClockIsoPort): Dict;
+/**
+ * Rejoin a public record with its secret envelope (auth-store.js:158-189).
+ * THE REFUSAL: when both sides name a computer_id and they disagree, the
+ * envelope is IGNORED wholesale — credentials from one machine identity
+ * must never dress up a record claiming another. On agreement the envelope
+ * only fills gaps; a value the record already carries always wins. Absent
+ * envelope values fill gaps as `''` — exactly the engine's bytes on disk.
+ */
+export declare function mergeRecordAuth(record: unknown, auth: unknown): Dict | null;
+/**
+ * May this stored record serve the runtime labeled `currentLabel`?
+ * (auth-store.js:191-199). The record's claim is read with key precedence
+ * runtime_label > label > branch through the NON-coercing normalizer, so a
+ * record with no recognizable label — one that predates labels — belongs
+ * to `main` and only main may claim it. Pure over the injected current
+ * label instead of module state.
+ */
+export declare function recordMatchesCurrentRuntime(record: unknown, currentLabel: string): boolean;
+/**
+ * The scope guard (auth-store.js:201-209): credentials for user A must
+ * never be saved into user B's scope. Enforced only when both sides are
+ * known and the scope is a real user — the `local` scope predates
+ * enrollment and accepts anyone. The refusal string is the ratified text.
+ */
+export declare function assertRecordMatchesUserScope(record: unknown, context: {
+    readonly runtimeLabel: string;
+    readonly userScope: string;
+}): void;
+/** Refresh proxy tokens 10 minutes before they die (auth-store.js:22,
+ * proxy-token-store.js:20) — one shared buffer, so the two freshness laws
+ * below can never disagree about "soon". */
+export declare const PROXY_REFRESH_BUFFER_MS: number;
+/**
+ * A record's proxy token under every spelling (auth-store.js:298-306), with
+ * an explicitly supplied environment override winning. Pure: the engine
+ * reads `process.env.AMALGM_PROXY_TOKEN`; the host passes that value in.
+ */
+export declare function proxyTokenFromRecord(record: unknown, envProxyToken?: string): string;
+/**
+ * The RECORD-side freshness law (auth-store.js:308-313), asked of a flat
+ * computer record: no token at all means refresh (true); a token whose
+ * expiry is missing or unparseable is trusted (false) — a legacy token
+ * without metadata keeps working; otherwise refresh inside the buffer.
+ * Note the deliberate asymmetry with {@link proxyTokenExpiresSoon}: over
+ * there, missing metadata means refresh — the envelope is expected to
+ * carry it.
+ */
+export declare function proxyTokenNeedsRefresh(record: unknown, ports: ClockMsPort, envProxyToken?: string): boolean;
+/**
+ * The ENVELOPE-side freshness law (proxy-token-store.js:110-117), asked of
+ * an auth envelope, three branches exactly: no token → false (nothing to
+ * refresh ahead of); token with missing OR unparseable expiry → true (an
+ * envelope is expected to know its expiry; not knowing is stale); else
+ * refresh inside the buffer.
+ */
+export declare function proxyTokenExpiresSoon(auth: unknown, ports: ClockMsPort): boolean;
+/** Everything a proxy-token refresh call needs, distilled from the pair. */
+export interface ProxyRefreshContext {
+    readonly machineToken: string;
+    readonly appUrl: string;
+    readonly computerId: string;
+    readonly deviceId: string;
+}
+/**
+ * The refresh-credential precedence chain (proxy-token-store.js:88-98):
+ * the machine token is the machine's own auth token first, the legacy flat
+ * spelling second, and — last resort — the tunnel token; addresses and ids
+ * prefer the record over the envelope.
+ */
+export declare function proxyRefreshContext(record: unknown, auth: unknown): ProxyRefreshContext;
+/**
+ * May a refresh even be attempted? (proxy-token-store.js:100-103): a
+ * machine token, an app URL, and a computer id are required; the device id
+ * is optional context.
+ */
+export declare function canRefreshProxyToken(context: {
+    readonly record: unknown;
+    readonly auth: unknown;
+}): boolean;
+/**
+ * The persisted `auth.json` after a successful proxy-token refresh
+ * (proxy-token-store.js:154-173): the prior envelope carried forward,
+ * identity restated from the refresh context, the server's answers winning
+ * over prior values field by field, and both `proxy.refreshed_at` and
+ * `updated_at` stamped now. `expires_in` collapses to undefined (dropped
+ * by JSON) when absent or zero. The caller guards with
+ * {@link canRefreshProxyToken}; this is only the shape law.
+ */
+export declare function refreshedProxyAuth(input: {
+    readonly record: unknown;
+    readonly auth: unknown;
+    readonly refreshed: unknown;
+}, ports: ClockIsoPort): Dict;
+export {};
+//# sourceMappingURL=auth-records.d.ts.map

package/dist/identity/auth-records.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-records.d.ts","sourceRoot":"","sources":["../../src/identity/auth-records.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE5D,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AASpC,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEzD;AAED,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAG3D;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAWnD,CAAC;AAEH;iEACiE;AACjE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAI3D;AAUD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,SAAc,GAAG,IAAI,CASlF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,OAAO,EACjB,KAAK,EAAE,YAAY,GAClB,IAAI,CA+DN;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,GAAG,IAAI,CAoC3E;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAK1F;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,OAAO,EACf,OAAO,EAAE;IAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACrE,IAAI,CAQN;AAED;;4CAE4C;AAC5C,eAAO,MAAM,uBAAuB,QAAiB,CAAC;AAEtD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EAAE,aAAa,SAAK,GAAG,MAAM,CAShF;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,WAAW,EAClB,aAAa,SAAK,GACjB,OAAO,CAMT;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAQhF;AAED,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,mBAAmB,CAcvF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAG3G;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAAE,EACxF,KAAK,EAAE,YAAY,GAClB,IAAI,CA0BN"}

package/dist/identity/auth-records.js

@@ -0,0 +1,354 @@
+/**
+ * Credential-record shaping laws (engine packages/amalgm/lib/auth-store.js
+ * and runtime/scripts/proxy-token-store.js) — how a computer record splits
+ * into its PUBLIC face (`computer.json`) and its SECRET envelope
+ * (`auth.json`), how the two merge back, and when a proxy token counts as
+ * fresh. Pure record computations only: reading, writing, and env access
+ * stay host-side; the clock arrives as a port.
+ *
+ * Records are loose JSON from disk, so inputs are typed as they truly are:
+ * dictionaries of unknowns, validated key by key.
+ */
+import { normalizeRuntimeLabel } from './labels.js';
+const asDict = (value) => (value && typeof value === 'object' ? value : null);
+function cleanString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : '';
+}
+/** Emails compare lowercased; a record's email is stored lowercased. */
+export function normalizeUserEmail(value) {
+    return cleanString(value).toLowerCase();
+}
+/** A record's email under any of its historical spellings (auth-store.js:74-76). */
+export function userEmailFromRecord(record) {
+    const r = asDict(record);
+    return normalizeUserEmail(r?.['user_email'] || r?.['userEmail'] || r?.['email']);
+}
+/**
+ * Every key that must NEVER appear in the public `computer.json`
+ * (auth-store.js:24-35). Secrets live only in `auth.json`; the exact list —
+ * including the legacy camelCase and hmac spellings — is the contract.
+ */
+export const SECRET_COMPUTER_KEYS = new Set([
+    'tunnel_token',
+    'computer_auth_token',
+    'proxy_token',
+    'proxy_token_expires_in',
+    'proxy_token_expires_at',
+    'proxy_token_refreshed_at',
+    'proxyToken',
+    'proxyTokenExpiresAt',
+    'hmac_token',
+    'hmacToken',
+]);
+/** Does this record carry any secret worth an auth envelope?
+ * (auth-store.js:78-81). Whitespace-only values do not count. */
+export function hasComputerSecrets(record) {
+    const r = asDict(record);
+    if (!r)
+        return false;
+    return Array.from(SECRET_COMPUTER_KEYS).some((key) => cleanString(r[key]));
+}
+/** The engine's `path.basename` over both separators, with trailing
+ * separators stripped — only the file's own name is published. */
+const baseName = (file) => {
+    const trimmed = file.replace(/[\\/]+$/, '');
+    const cut = Math.max(trimmed.lastIndexOf('/'), trimmed.lastIndexOf('\\'));
+    return cut === -1 ? trimmed : trimmed.slice(cut + 1);
+};
+/**
+ * The public face of a computer record (auth-store.js:83-92): the record
+ * with every secret key removed, its email normalized, and an `auth_file`
+ * pointer naming the sibling envelope by BASENAME — the record must stay
+ * true when the directory moves. DELIBERATE DEVIATION: the engine's
+ * parameter is a full path passed through `node:path.basename`; the same
+ * basename law is implemented here inline to stay dependency-free.
+ */
+export function publicComputerRecord(record, authFile = 'auth.json') {
+    const out = {
+        ...(asDict(record) || {}),
+        auth_file: baseName(authFile),
+    };
+    const email = userEmailFromRecord(out);
+    if (email)
+        out['user_email'] = email;
+    for (const key of SECRET_COMPUTER_KEYS)
+        delete out[key];
+    return out;
+}
+/**
+ * The full secret envelope distilled from a computer record
+ * (auth-store.js:94-156):
+ *
+ *   { schema_version: 1, computer_id, device_id, user_id, user_email,
+ *     app_url, tunnel: { token, url, chat_tunnel_url }, machine: { token },
+ *     proxy: { token, expires_in, expires_at, refreshed_at } }
+ *
+ * Merging over `existing` is additive: identity keys are copied only when
+ * the record actually carries them, each token section is (re)stamped only
+ * when its token arrives, and a record carrying only tunnel URLs updates
+ * the URLs while PRESERVING the existing tunnel token. `expires_in`
+ * collapses to undefined (dropped by JSON) when absent or zero. Legacy
+ * proxy-token spellings (proxyToken, hmac_token, hmacToken) are honored on
+ * input; the envelope speaks only the canonical shape.
+ */
+export function authFromRecord(record, existing, ports) {
+    const now = ports.nowIso();
+    const r = asDict(record);
+    const auth = {
+        schema_version: 1,
+        ...(asDict(existing) || {}),
+        updated_at: now,
+    };
+    for (const key of ['computer_id', 'device_id', 'user_id', 'user_email', 'app_url']) {
+        const value = key === 'user_email' ? userEmailFromRecord(r) : cleanString(r?.[key]);
+        if (value)
+            auth[key] = value;
+    }
+    const priorTunnel = asDict(auth['tunnel']);
+    const tunnelToken = cleanString(r?.['tunnel_token']);
+    if (tunnelToken) {
+        auth['tunnel'] = {
+            ...(priorTunnel || {}),
+            token: tunnelToken,
+            url: cleanString(r?.['tunnel_url']) || cleanString(priorTunnel?.['url']),
+            chat_tunnel_url: cleanString(r?.['chat_tunnel_url']) || cleanString(priorTunnel?.['chat_tunnel_url']),
+            updated_at: now,
+        };
+    }
+    else if (r?.['tunnel_url'] || r?.['chat_tunnel_url']) {
+        auth['tunnel'] = {
+            ...(priorTunnel || {}),
+            url: cleanString(r?.['tunnel_url']) || cleanString(priorTunnel?.['url']),
+            chat_tunnel_url: cleanString(r?.['chat_tunnel_url']) || cleanString(priorTunnel?.['chat_tunnel_url']),
+        };
+    }
+    const computerAuthToken = cleanString(r?.['computer_auth_token']);
+    if (computerAuthToken) {
+        auth['machine'] = {
+            ...(asDict(auth['machine']) || {}),
+            token: computerAuthToken,
+            updated_at: now,
+        };
+    }
+    const proxyToken = (cleanString(r?.['proxy_token'])
+        || cleanString(r?.['proxyToken'])
+        || cleanString(r?.['hmac_token'])
+        || cleanString(r?.['hmacToken']));
+    if (proxyToken) {
+        const priorProxy = asDict(auth['proxy']);
+        auth['proxy'] = {
+            ...(priorProxy || {}),
+            token: proxyToken,
+            expires_in: Number(r?.['proxy_token_expires_in'] || priorProxy?.['expires_in'] || 0) || undefined,
+            expires_at: cleanString(r?.['proxy_token_expires_at'])
+                || cleanString(r?.['proxyTokenExpiresAt'])
+                || cleanString(priorProxy?.['expires_at']),
+            refreshed_at: cleanString(r?.['proxy_token_refreshed_at'])
+                || cleanString(priorProxy?.['refreshed_at'])
+                || now,
+        };
+    }
+    return auth;
+}
+/**
+ * Rejoin a public record with its secret envelope (auth-store.js:158-189).
+ * THE REFUSAL: when both sides name a computer_id and they disagree, the
+ * envelope is IGNORED wholesale — credentials from one machine identity
+ * must never dress up a record claiming another. On agreement the envelope
+ * only fills gaps; a value the record already carries always wins. Absent
+ * envelope values fill gaps as `''` — exactly the engine's bytes on disk.
+ */
+export function mergeRecordAuth(record, auth) {
+    const r = asDict(record);
+    if (!r)
+        return null;
+    const merged = { ...r };
+    const a = asDict(auth);
+    if (!a)
+        return merged;
+    const authComputerId = cleanString(a['computer_id']);
+    const recordComputerId = cleanString(r['computer_id']);
+    if (authComputerId && recordComputerId && authComputerId !== recordComputerId)
+        return merged;
+    const tunnel = asDict(a['tunnel']);
+    const machine = asDict(a['machine']);
+    const proxy = asDict(a['proxy']);
+    if (!merged['tunnel_token'])
+        merged['tunnel_token'] = cleanString(tunnel?.['token']) || cleanString(a['tunnel_token']);
+    if (!merged['tunnel_url'])
+        merged['tunnel_url'] = cleanString(tunnel?.['url']);
+    if (!merged['chat_tunnel_url'])
+        merged['chat_tunnel_url'] = cleanString(tunnel?.['chat_tunnel_url']);
+    if (!merged['computer_auth_token']) {
+        merged['computer_auth_token'] = cleanString(machine?.['token']) || cleanString(a['computer_auth_token']);
+    }
+    if (!merged['proxy_token']) {
+        merged['proxy_token'] = cleanString(proxy?.['token']) || cleanString(a['proxy_token']);
+    }
+    if (!merged['proxy_token_expires_at']) {
+        merged['proxy_token_expires_at'] = cleanString(proxy?.['expires_at']) || cleanString(a['proxy_token_expires_at']);
+    }
+    if (!merged['proxy_token_expires_in'] && proxy?.['expires_in']) {
+        merged['proxy_token_expires_in'] = proxy['expires_in'];
+    }
+    if (!merged['proxy_token_refreshed_at']) {
+        merged['proxy_token_refreshed_at'] = cleanString(proxy?.['refreshed_at']);
+    }
+    if (!merged['user_id'])
+        merged['user_id'] = cleanString(a['user_id']);
+    if (!merged['user_email'])
+        merged['user_email'] = normalizeUserEmail(a['user_email']);
+    if (!merged['app_url'])
+        merged['app_url'] = cleanString(a['app_url']);
+    return merged;
+}
+/**
+ * May this stored record serve the runtime labeled `currentLabel`?
+ * (auth-store.js:191-199). The record's claim is read with key precedence
+ * runtime_label > label > branch through the NON-coercing normalizer, so a
+ * record with no recognizable label — one that predates labels — belongs
+ * to `main` and only main may claim it. Pure over the injected current
+ * label instead of module state.
+ */
+export function recordMatchesCurrentRuntime(record, currentLabel) {
+    const r = asDict(record);
+    const label = normalizeRuntimeLabel(r?.['runtime_label'] || r?.['label'] || r?.['branch']);
+    if (!label)
+        return currentLabel === 'main';
+    return label === currentLabel;
+}
+/**
+ * The scope guard (auth-store.js:201-209): credentials for user A must
+ * never be saved into user B's scope. Enforced only when both sides are
+ * known and the scope is a real user — the `local` scope predates
+ * enrollment and accepts anyone. The refusal string is the ratified text.
+ */
+export function assertRecordMatchesUserScope(record, context) {
+    const userId = cleanString(asDict(record)?.['user_id']);
+    const expectedScope = cleanString(context.userScope);
+    if (!userId || !expectedScope || expectedScope === 'local')
+        return;
+    if (userId === expectedScope)
+        return;
+    throw new Error(`Refusing to save ${context.runtimeLabel} computer credentials for user ${userId} in scope ${expectedScope}.`);
+}
+/** Refresh proxy tokens 10 minutes before they die (auth-store.js:22,
+ * proxy-token-store.js:20) — one shared buffer, so the two freshness laws
+ * below can never disagree about "soon". */
+export const PROXY_REFRESH_BUFFER_MS = 10 * 60 * 1000;
+/**
+ * A record's proxy token under every spelling (auth-store.js:298-306), with
+ * an explicitly supplied environment override winning. Pure: the engine
+ * reads `process.env.AMALGM_PROXY_TOKEN`; the host passes that value in.
+ */
+export function proxyTokenFromRecord(record, envProxyToken = '') {
+    const r = asDict(record);
+    return (cleanString(envProxyToken)
+        || cleanString(r?.['proxy_token'])
+        || cleanString(r?.['proxyToken'])
+        || cleanString(r?.['hmac_token'])
+        || cleanString(r?.['hmacToken']));
+}
+/**
+ * The RECORD-side freshness law (auth-store.js:308-313), asked of a flat
+ * computer record: no token at all means refresh (true); a token whose
+ * expiry is missing or unparseable is trusted (false) — a legacy token
+ * without metadata keeps working; otherwise refresh inside the buffer.
+ * Note the deliberate asymmetry with {@link proxyTokenExpiresSoon}: over
+ * there, missing metadata means refresh — the envelope is expected to
+ * carry it.
+ */
+export function proxyTokenNeedsRefresh(record, ports, envProxyToken = '') {
+    if (!proxyTokenFromRecord(record, envProxyToken))
+        return true;
+    const r = asDict(record);
+    const expiresAt = Date.parse(String(r?.['proxy_token_expires_at'] || r?.['proxyTokenExpiresAt'] || ''));
+    if (!Number.isFinite(expiresAt))
+        return false;
+    return expiresAt - ports.nowMs() < PROXY_REFRESH_BUFFER_MS;
+}
+/**
+ * The ENVELOPE-side freshness law (proxy-token-store.js:110-117), asked of
+ * an auth envelope, three branches exactly: no token → false (nothing to
+ * refresh ahead of); token with missing OR unparseable expiry → true (an
+ * envelope is expected to know its expiry; not knowing is stale); else
+ * refresh inside the buffer.
+ */
+export function proxyTokenExpiresSoon(auth, ports) {
+    const proxy = asDict(asDict(auth)?.['proxy']);
+    if (!cleanString(proxy?.['token']))
+        return false;
+    const expiresAtRaw = cleanString(proxy?.['expires_at']);
+    if (!expiresAtRaw)
+        return true;
+    const expiresAt = Date.parse(expiresAtRaw);
+    if (!Number.isFinite(expiresAt))
+        return true;
+    return expiresAt - ports.nowMs() < PROXY_REFRESH_BUFFER_MS;
+}
+/**
+ * The refresh-credential precedence chain (proxy-token-store.js:88-98):
+ * the machine token is the machine's own auth token first, the legacy flat
+ * spelling second, and — last resort — the tunnel token; addresses and ids
+ * prefer the record over the envelope.
+ */
+export function proxyRefreshContext(record, auth) {
+    const r = asDict(record);
+    const a = asDict(auth);
+    const machine = asDict(a?.['machine']);
+    const tunnel = asDict(a?.['tunnel']);
+    return {
+        machineToken: cleanString(machine?.['token'])
+            || cleanString(a?.['computer_auth_token'])
+            || cleanString(tunnel?.['token']),
+        appUrl: cleanString(r?.['app_url']) || cleanString(a?.['app_url']),
+        computerId: cleanString(r?.['computer_id']) || cleanString(a?.['computer_id']),
+        deviceId: cleanString(r?.['device_id']) || cleanString(a?.['device_id']),
+    };
+}
+/**
+ * May a refresh even be attempted? (proxy-token-store.js:100-103): a
+ * machine token, an app URL, and a computer id are required; the device id
+ * is optional context.
+ */
+export function canRefreshProxyToken(context) {
+    const refresh = proxyRefreshContext(context.record, context.auth);
+    return !!(refresh.machineToken && refresh.appUrl && refresh.computerId);
+}
+/**
+ * The persisted `auth.json` after a successful proxy-token refresh
+ * (proxy-token-store.js:154-173): the prior envelope carried forward,
+ * identity restated from the refresh context, the server's answers winning
+ * over prior values field by field, and both `proxy.refreshed_at` and
+ * `updated_at` stamped now. `expires_in` collapses to undefined (dropped
+ * by JSON) when absent or zero. The caller guards with
+ * {@link canRefreshProxyToken}; this is only the shape law.
+ */
+export function refreshedProxyAuth(input, ports) {
+    const { appUrl, computerId, deviceId } = proxyRefreshContext(input.record, input.auth);
+    const r = asDict(input.record);
+    const a = asDict(input.auth) || {};
+    const refreshed = asDict(input.refreshed);
+    const priorProxy = asDict(a['proxy']);
+    const now = ports.nowIso();
+    return {
+        ...a,
+        schema_version: 1,
+        computer_id: computerId,
+        device_id: deviceId,
+        user_id: cleanString(r?.['user_id']) || cleanString(a['user_id']),
+        user_email: cleanString(refreshed?.['user_email']).toLowerCase()
+            || cleanString(r?.['user_email']).toLowerCase()
+            || cleanString(a['user_email']).toLowerCase(),
+        app_url: appUrl,
+        proxy: {
+            ...(priorProxy || {}),
+            token: cleanString(refreshed?.['proxy_token']) || cleanString(priorProxy?.['token']),
+            expires_in: Number(refreshed?.['proxy_token_expires_in'] || priorProxy?.['expires_in'] || 0) || undefined,
+            expires_at: cleanString(refreshed?.['proxy_token_expires_at']) || cleanString(priorProxy?.['expires_at']),
+            refreshed_at: now,
+        },
+        updated_at: now,
+    };
+}
+//# sourceMappingURL=auth-records.js.map