@amalgm/core 0.1.0

package/dist/identity/layout.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Filesystem-layout grammar — the names, manifests, and path shapes of
+ * `~/amalgm` (engine runtime/scripts/amalgm-mcp/lib/layout.js, mirrored
+ * byte-for-byte in packages/amalgm/lib/layout.js modulo one comment; and
+ * runtime/scripts/lib/runtime-paths.js). PURE laws only: every function
+ * here is a string/record computation. Reading, writing, migrating, and
+ * resolving against the real filesystem stay host-side.
+ *
+ * The layout's own law: the folder name is presentation, the manifest is
+ * identity. `.amalgm-user.json`'s userId is authoritative; a renamed folder
+ * is recovered by manifest scan, never by trusting its name.
+ *
+ * Path joins here are POSIX (`/`). DELIBERATE DEVIATION: the engine joins
+ * with `path.join`, so on Windows it emits `\` — identical bytes on
+ * macOS/Linux, where every shipped runtime lives. The grammar (segment
+ * names and nesting) is the law; the separator belongs to the host.
+ */
+import type { ClockIsoPort, RandomHexPort } from './ports.js';
+/** Installation identity + user-folder index, at the amalgm root
+ * (layout.js:32). */
+export declare const ROOT_MANIFEST_NAME = ".amalgm-root.json";
+/** Stable user identity inside a user folder (layout.js:33). */
+export declare const USER_MANIFEST_NAME = ".amalgm-user.json";
+/** Root/user manifest schema version (layout.js:34). */
+export declare const LAYOUT_VERSION = 1;
+/** Basename of the user-home manifest (layout.js:35). The file itself lives
+ * at `system/home.json` inside the user dir — the `home-manifest` entry of
+ * {@link shippedUserHomeDeclaration}. */
+export declare const USER_HOME_MANIFEST_NAME = "home.json";
+/** User-home graph schema version (layout.js:38). Changing the declared
+ * exact graph changes the identity contract: a client must never accept a
+ * prior graph and silently invent a new managed child. */
+export declare const USER_HOME_SCHEMA_VERSION = 2;
+/** Stable per-user product namespaces (layout.js:43-50). Their authority is
+ * NOT inferred from their path: user content and exact platform-managed
+ * targets are declared separately in the user-home declaration.
+ * DELIBERATE DEVIATION: `browser` is an SDK-side ADDITION ahead of the
+ * engine — the browser brick keeps per-user state and needs a declared
+ * namespace to resolve it into ({@link resolveProductStateDir}). Additive
+ * only (axiom 7): the engine's six keep their bytes and order; it does NOT
+ * join the shipped user-home graph until the browser product declares it. */
+export declare const PRIMITIVE_DIRS: readonly string[];
+/**
+ * ONE sanitizer, two engine homes: runtime-identity.js:59-65
+ * (`sanitizeScopeSegment`) and layout.js:161-167 (`sanitizeFolderSegment`)
+ * carry the deliberately identical charset `[^A-Za-z0-9_.@-] → _`, trimmed
+ * of leading/trailing underscores, falling back to `'local'` — kept in
+ * lockstep so legacy uuid folders resolve to the exact names they were
+ * created with. Ported once; {@link sanitizeFolderSegment} is the same
+ * function under its layout-side name.
+ */
+export declare function sanitizeScopeSegment(value: unknown, fallback?: string): string;
+/** The shared sanitizer under its layout.js name — the same function, not a
+ * copy, so the two names can never drift. */
+export declare const sanitizeFolderSegment: typeof sanitizeScopeSegment;
+/** Folder name for a user identified by email (layout.js:170-172):
+ * lowercased, same charset, and — unlike a scope — an empty email yields
+ * `''`, never the `'local'` fallback. */
+export declare function emailFolderName(email: unknown): string;
+/** A root under the user dir that holds user content. */
+export interface UserHomeRootDeclaration {
+    readonly key: string;
+    readonly relativePath: string;
+}
+/** An exact platform-managed node. Management is an exact-node fact — it
+ * deliberately does not cascade from `system/`. */
+export interface UserHomeExactManagedDeclaration {
+    readonly key: string;
+    readonly relativePath: string;
+    readonly rootKey: string;
+    readonly toolId?: string;
+}
+/** What a user home contains: content roots plus the exact managed graph. */
+export interface UserHomeDeclaration {
+    readonly roots: readonly UserHomeRootDeclaration[];
+    readonly exactManaged: readonly UserHomeExactManagedDeclaration[];
+}
+export interface ShippedUserHomeDeclaration extends UserHomeDeclaration {
+    readonly systemToolArtifacts: readonly UserHomeExactManagedDeclaration[];
+}
+/**
+ * The user-home graph the engine ships today (layout.js:52-87): the six
+ * roots, one `<key>-root` managed node per root, the home manifest at
+ * `system/home.json`, `system/defaults`, `system/policy`, and the seven
+ * system tool artifacts. These CONTENTS are PRODUCT declarations, not
+ * kernel law — the builder ({@link buildUserHomeManifest}) takes any
+ * declaration as input. The shipped set lives here only until the products
+ * register their own declarations.
+ */
+export declare const shippedUserHomeDeclaration: ShippedUserHomeDeclaration;
+/** The persisted `system/home.json` contents (layout.js:137-146). */
+export interface UserHomeManifest {
+    readonly schemaVersion: number;
+    readonly kind: 'amalgm-user-home';
+    readonly roots: readonly {
+        readonly key: string;
+        readonly path: string;
+    }[];
+    readonly exactManaged: readonly {
+        readonly key: string;
+        readonly path: string;
+        readonly scope: 'exact';
+    }[];
+}
+/**
+ * The user-home manifest for a declaration (engine ensureUserHome's
+ * `manifestContents`, layout.js:137-146): schemaVersion 2, kind
+ * `amalgm-user-home`, and the declaration's entries with each
+ * `relativePath` published under the key name `path` — relative, so the
+ * manifest survives a moved or renamed user folder — and every managed
+ * node stamped `scope: 'exact'`.
+ */
+export declare function buildUserHomeManifest(declaration: UserHomeDeclaration): UserHomeManifest;
+/** `.amalgm-root.json` — installation identity plus the user-folder index
+ * (a cache; user-manifest scans stay authoritative). */
+export interface RootManifest {
+    readonly schemaVersion: number;
+    readonly installationId: string;
+    readonly createdAt: string;
+    readonly users: Record<string, unknown>;
+}
+/**
+ * The root manifest an installation should hold (engine ensureRootManifest,
+ * layout.js:234-245, minus the write): an existing manifest that already
+ * carries an installationId is returned untouched — installation identity
+ * is minted once, never re-rolled — otherwise a fresh manifest is built,
+ * preserving any partial `createdAt`/`users`, with an 8-byte hex
+ * installationId from the injected randomness.
+ */
+export declare function buildRootManifest(existing: Partial<RootManifest> | null | undefined, ports: ClockIsoPort & RandomHexPort): RootManifest;
+/** `.amalgm-user.json` — the stable identity of a user folder. */
+export interface UserManifest {
+    readonly schemaVersion: number;
+    readonly userId: string;
+    readonly canonicalEmail: string;
+    readonly emailHistory: readonly unknown[];
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+/**
+ * The next user manifest (engine writeUserManifest, layout.js:262-277,
+ * minus the write): userId trimmed, canonicalEmail lowercased with the
+ * existing email as fallback, and emailHistory APPEND-ONLY — a new
+ * canonical email joins the history, nothing ever leaves it, so every name
+ * this user has worn stays resolvable. `createdAt` is preserved;
+ * `updatedAt` is stamped now.
+ */
+export declare function buildUserManifest(identity: {
+    readonly userId: string;
+    readonly email?: unknown;
+}, existing: Partial<UserManifest> | null | undefined, ports: ClockIsoPort): UserManifest;
+/** THE path join of this grammar: segments glued with `/`, nothing
+ * normalized (see the header's deliberate-deviation note on separators).
+ * Exported so callers composing onto these paths use the same law instead
+ * of reaching for `node:path`, which axiom 6 forbids them anyway. */
+export declare function joinPathSegments(...segments: string[]): string;
+/**
+ * The name-derived user dir: `<homeDir>/users/<sanitized scope>` (engine
+ * scopedAmalgmDir, runtime-identity.js:137-142). DELIBERATE DEVIATION: the
+ * engine signature takes a third `label` parameter it asserts and then
+ * IGNORES — vestigial since manifest identity won over label-scoped
+ * folders — so the honest signature drops it. This is only the fallback
+ * path grammar: manifest-based resolution (find-by-userId across
+ * `.amalgm-user.json` files) reads the filesystem and stays host-side.
+ */
+export declare function scopedAmalgmDir(homeDir: string, userScope: unknown): string;
+/** Per-label runtime state: `<userDir>/runtimes/<label>` (engine
+ * scopedRuntimeDir runtime-identity.js:144-146, runtime-paths.js:81-86).
+ * The label must be one of the three — junk never names a state dir. */
+export declare function runtimeStateDir(userDir: string, label: string): string;
+/** `runtime-state.json` inside a runtime state dir (runtime-paths.js:88-90). */
+export declare function runtimeStateFile(stateDir: string): string;
+/** `runtime-token.json` inside a runtime state dir (runtime-paths.js:92-94). */
+export declare function runtimeTokenFile(stateDir: string): string;
+/** `logs/` inside a runtime state dir (runtime-paths.js:96-98). */
+export declare function runtimeLogDir(stateDir: string): string;
+/** `computer.json` — the public computer record beside a state or user dir
+ * (engine config.js:37-40, proxy-token-store.js:25-28). */
+export declare function computerRecordFile(dir: string): string;
+/** `auth.json` — the secret auth envelope beside a state or user dir
+ * (engine config.js:37-40, proxy-token-store.js:25-28). */
+export declare function computerAuthFile(dir: string): string;
+/**
+ * A primitive root under the user dir (layout.js:414-419). Only the six
+ * declared namespaces exist; the refusal string is the ratified text.
+ */
+export declare function userPrimitiveRoot(userDir: string, kind: string): string;
+//# sourceMappingURL=layout.d.ts.map

package/dist/identity/layout.d.ts.map

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

package/dist/identity/layout.js

@@ -0,0 +1,233 @@
+/**
+ * Filesystem-layout grammar — the names, manifests, and path shapes of
+ * `~/amalgm` (engine runtime/scripts/amalgm-mcp/lib/layout.js, mirrored
+ * byte-for-byte in packages/amalgm/lib/layout.js modulo one comment; and
+ * runtime/scripts/lib/runtime-paths.js). PURE laws only: every function
+ * here is a string/record computation. Reading, writing, migrating, and
+ * resolving against the real filesystem stay host-side.
+ *
+ * The layout's own law: the folder name is presentation, the manifest is
+ * identity. `.amalgm-user.json`'s userId is authoritative; a renamed folder
+ * is recovered by manifest scan, never by trusting its name.
+ *
+ * Path joins here are POSIX (`/`). DELIBERATE DEVIATION: the engine joins
+ * with `path.join`, so on Windows it emits `\` — identical bytes on
+ * macOS/Linux, where every shipped runtime lives. The grammar (segment
+ * names and nesting) is the law; the separator belongs to the host.
+ */
+import { assertRuntimeLabel } from './labels.js';
+/** Installation identity + user-folder index, at the amalgm root
+ * (layout.js:32). */
+export const ROOT_MANIFEST_NAME = '.amalgm-root.json';
+/** Stable user identity inside a user folder (layout.js:33). */
+export const USER_MANIFEST_NAME = '.amalgm-user.json';
+/** Root/user manifest schema version (layout.js:34). */
+export const LAYOUT_VERSION = 1;
+/** Basename of the user-home manifest (layout.js:35). The file itself lives
+ * at `system/home.json` inside the user dir — the `home-manifest` entry of
+ * {@link shippedUserHomeDeclaration}. */
+export const USER_HOME_MANIFEST_NAME = 'home.json';
+/** User-home graph schema version (layout.js:38). Changing the declared
+ * exact graph changes the identity contract: a client must never accept a
+ * prior graph and silently invent a new managed child. */
+export const USER_HOME_SCHEMA_VERSION = 2;
+/** Stable per-user product namespaces (layout.js:43-50). Their authority is
+ * NOT inferred from their path: user content and exact platform-managed
+ * targets are declared separately in the user-home declaration.
+ * DELIBERATE DEVIATION: `browser` is an SDK-side ADDITION ahead of the
+ * engine — the browser brick keeps per-user state and needs a declared
+ * namespace to resolve it into ({@link resolveProductStateDir}). Additive
+ * only (axiom 7): the engine's six keep their bytes and order; it does NOT
+ * join the shipped user-home graph until the browser product declares it. */
+export const PRIMITIVE_DIRS = Object.freeze([
+    'agents',
+    'apps',
+    'automations',
+    'toolbox',
+    'workspaces',
+    'system',
+    'browser',
+]);
+/**
+ * ONE sanitizer, two engine homes: runtime-identity.js:59-65
+ * (`sanitizeScopeSegment`) and layout.js:161-167 (`sanitizeFolderSegment`)
+ * carry the deliberately identical charset `[^A-Za-z0-9_.@-] → _`, trimmed
+ * of leading/trailing underscores, falling back to `'local'` — kept in
+ * lockstep so legacy uuid folders resolve to the exact names they were
+ * created with. Ported once; {@link sanitizeFolderSegment} is the same
+ * function under its layout-side name.
+ */
+export function sanitizeScopeSegment(value, fallback = 'local') {
+    const clean = String(value || '')
+        .trim()
+        .replace(/[^A-Za-z0-9_.@-]/g, '_')
+        .replace(/^_+|_+$/g, '');
+    return clean || fallback;
+}
+/** The shared sanitizer under its layout.js name — the same function, not a
+ * copy, so the two names can never drift. */
+export const sanitizeFolderSegment = sanitizeScopeSegment;
+/** Folder name for a user identified by email (layout.js:170-172):
+ * lowercased, same charset, and — unlike a scope — an empty email yields
+ * `''`, never the `'local'` fallback. */
+export function emailFolderName(email) {
+    return sanitizeFolderSegment(String(email || '').trim().toLowerCase(), '');
+}
+const USER_HOME_ROOTS = Object.freeze([
+    { key: 'agents', relativePath: 'agents' },
+    { key: 'apps', relativePath: 'apps' },
+    { key: 'automations', relativePath: 'automations' },
+    { key: 'toolbox', relativePath: 'toolbox' },
+    { key: 'workspaces', relativePath: 'workspaces' },
+    { key: 'system', relativePath: 'system' },
+]);
+// A Toolbox tool is one complete entity: its definition and actions travel
+// in the same file. These names are deliberately stable and human-readable.
+const SYSTEM_TOOL_ARTIFACTS = Object.freeze([
+    { key: 'amalgm-automations', toolId: 'automations', relativePath: 'toolbox/amalgm-automations.json', rootKey: 'toolbox' },
+    { key: 'amalgm-notifications', toolId: 'notifications', relativePath: 'toolbox/amalgm-notifications.json', rootKey: 'toolbox' },
+    { key: 'amalgm-memories', toolId: 'memories', relativePath: 'toolbox/amalgm-memories.json', rootKey: 'toolbox' },
+    { key: 'amalgm-agents', toolId: 'agents', relativePath: 'toolbox/amalgm-agents.json', rootKey: 'toolbox' },
+    { key: 'amalgm-apps', toolId: 'apps', relativePath: 'toolbox/amalgm-apps.json', rootKey: 'toolbox' },
+    { key: 'amalgm-cua', toolId: 'computer-use', relativePath: 'toolbox/amalgm-cua.json', rootKey: 'toolbox' },
+    { key: 'amalgm-browser', toolId: 'browser', relativePath: 'toolbox/amalgm-browser.json', rootKey: 'toolbox' },
+]);
+/**
+ * The user-home graph the engine ships today (layout.js:52-87): the six
+ * roots, one `<key>-root` managed node per root, the home manifest at
+ * `system/home.json`, `system/defaults`, `system/policy`, and the seven
+ * system tool artifacts. These CONTENTS are PRODUCT declarations, not
+ * kernel law — the builder ({@link buildUserHomeManifest}) takes any
+ * declaration as input. The shipped set lives here only until the products
+ * register their own declarations.
+ */
+export const shippedUserHomeDeclaration = Object.freeze({
+    roots: USER_HOME_ROOTS,
+    systemToolArtifacts: SYSTEM_TOOL_ARTIFACTS,
+    exactManaged: Object.freeze([
+        ...USER_HOME_ROOTS.map(({ key, relativePath }) => ({
+            key: `${key}-root`, relativePath, rootKey: key,
+        })),
+        { key: 'home-manifest', relativePath: 'system/home.json', rootKey: 'system' },
+        { key: 'defaults', relativePath: 'system/defaults', rootKey: 'system' },
+        { key: 'policy', relativePath: 'system/policy', rootKey: 'system' },
+        ...SYSTEM_TOOL_ARTIFACTS,
+    ]),
+});
+/**
+ * The user-home manifest for a declaration (engine ensureUserHome's
+ * `manifestContents`, layout.js:137-146): schemaVersion 2, kind
+ * `amalgm-user-home`, and the declaration's entries with each
+ * `relativePath` published under the key name `path` — relative, so the
+ * manifest survives a moved or renamed user folder — and every managed
+ * node stamped `scope: 'exact'`.
+ */
+export function buildUserHomeManifest(declaration) {
+    return {
+        schemaVersion: USER_HOME_SCHEMA_VERSION,
+        kind: 'amalgm-user-home',
+        roots: declaration.roots.map(({ key, relativePath }) => ({ key, path: relativePath })),
+        exactManaged: declaration.exactManaged.map(({ key, relativePath }) => ({
+            key, path: relativePath, scope: 'exact',
+        })),
+    };
+}
+/**
+ * The root manifest an installation should hold (engine ensureRootManifest,
+ * layout.js:234-245, minus the write): an existing manifest that already
+ * carries an installationId is returned untouched — installation identity
+ * is minted once, never re-rolled — otherwise a fresh manifest is built,
+ * preserving any partial `createdAt`/`users`, with an 8-byte hex
+ * installationId from the injected randomness.
+ */
+export function buildRootManifest(existing, ports) {
+    if (existing?.installationId)
+        return existing;
+    return {
+        schemaVersion: LAYOUT_VERSION,
+        installationId: existing?.installationId || ports.randomHex(8),
+        createdAt: existing?.createdAt || ports.nowIso(),
+        users: existing?.users || {},
+    };
+}
+/**
+ * The next user manifest (engine writeUserManifest, layout.js:262-277,
+ * minus the write): userId trimmed, canonicalEmail lowercased with the
+ * existing email as fallback, and emailHistory APPEND-ONLY — a new
+ * canonical email joins the history, nothing ever leaves it, so every name
+ * this user has worn stays resolvable. `createdAt` is preserved;
+ * `updatedAt` is stamped now.
+ */
+export function buildUserManifest(identity, existing, ports) {
+    const canonicalEmail = String(identity.email || existing?.canonicalEmail || '').trim().toLowerCase();
+    const emailHistory = Array.isArray(existing?.emailHistory) ? [...existing.emailHistory] : [];
+    if (canonicalEmail && !emailHistory.includes(canonicalEmail))
+        emailHistory.push(canonicalEmail);
+    return {
+        schemaVersion: LAYOUT_VERSION,
+        userId: String(identity.userId).trim(),
+        canonicalEmail,
+        emailHistory,
+        createdAt: existing?.createdAt || ports.nowIso(),
+        updatedAt: ports.nowIso(),
+    };
+}
+/** THE path join of this grammar: segments glued with `/`, nothing
+ * normalized (see the header's deliberate-deviation note on separators).
+ * Exported so callers composing onto these paths use the same law instead
+ * of reaching for `node:path`, which axiom 6 forbids them anyway. */
+export function joinPathSegments(...segments) {
+    return segments.join('/');
+}
+const join = joinPathSegments;
+/**
+ * The name-derived user dir: `<homeDir>/users/<sanitized scope>` (engine
+ * scopedAmalgmDir, runtime-identity.js:137-142). DELIBERATE DEVIATION: the
+ * engine signature takes a third `label` parameter it asserts and then
+ * IGNORES — vestigial since manifest identity won over label-scoped
+ * folders — so the honest signature drops it. This is only the fallback
+ * path grammar: manifest-based resolution (find-by-userId across
+ * `.amalgm-user.json` files) reads the filesystem and stays host-side.
+ */
+export function scopedAmalgmDir(homeDir, userScope) {
+    return join(homeDir, 'users', sanitizeScopeSegment(userScope));
+}
+/** Per-label runtime state: `<userDir>/runtimes/<label>` (engine
+ * scopedRuntimeDir runtime-identity.js:144-146, runtime-paths.js:81-86).
+ * The label must be one of the three — junk never names a state dir. */
+export function runtimeStateDir(userDir, label) {
+    return join(userDir, 'runtimes', assertRuntimeLabel(label));
+}
+/** `runtime-state.json` inside a runtime state dir (runtime-paths.js:88-90). */
+export function runtimeStateFile(stateDir) {
+    return join(stateDir, 'runtime-state.json');
+}
+/** `runtime-token.json` inside a runtime state dir (runtime-paths.js:92-94). */
+export function runtimeTokenFile(stateDir) {
+    return join(stateDir, 'runtime-token.json');
+}
+/** `logs/` inside a runtime state dir (runtime-paths.js:96-98). */
+export function runtimeLogDir(stateDir) {
+    return join(stateDir, 'logs');
+}
+/** `computer.json` — the public computer record beside a state or user dir
+ * (engine config.js:37-40, proxy-token-store.js:25-28). */
+export function computerRecordFile(dir) {
+    return join(dir, 'computer.json');
+}
+/** `auth.json` — the secret auth envelope beside a state or user dir
+ * (engine config.js:37-40, proxy-token-store.js:25-28). */
+export function computerAuthFile(dir) {
+    return join(dir, 'auth.json');
+}
+/**
+ * A primitive root under the user dir (layout.js:414-419). Only the six
+ * declared namespaces exist; the refusal string is the ratified text.
+ */
+export function userPrimitiveRoot(userDir, kind) {
+    if (!PRIMITIVE_DIRS.includes(kind)) {
+        throw new Error(`Unknown primitive root "${kind}". Use one of: ${PRIMITIVE_DIRS.join(', ')}`);
+    }
+    return join(userDir, kind);
+}
+//# sourceMappingURL=layout.js.map

package/dist/identity/layout.js.map

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

package/dist/identity/ports.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Effect ports — axiom 6: a host supplies its own effects. Nothing in src/
+ * reads a clock, randomness source, hash, path resolver, or environment
+ * variable; each law that needs an effect names the narrow power here and
+ * receives it from the caller. The engine call each port replaces is cited
+ * so parity stays checkable.
+ */
+/** Wall-clock as an ISO-8601 string — the engine's `new Date().toISOString()`. */
+export interface ClockIsoPort {
+    nowIso(): string;
+}
+/** Wall-clock in epoch milliseconds — the engine's `Date.now()`. */
+export interface ClockMsPort {
+    nowMs(): number;
+}
+/** Cryptographic randomness as lowercase hex over `byteCount` bytes — the
+ * engine's `crypto.randomBytes(byteCount).toString('hex')`. */
+export interface RandomHexPort {
+    randomHex(byteCount: number): string;
+}
+/** SHA-256 of a UTF-8 string as lowercase hex — the engine's
+ * `crypto.createHash('sha256').update(input, 'utf8').digest('hex')`. */
+export interface Sha256HexPort {
+    sha256Hex(input: string): string;
+}
+/** Absolute-path resolution — the engine's `path.resolve`. Injected because
+ * resolution consults the working directory, an ambient effect. */
+export interface ResolvePathPort {
+    resolvePath(target: string): string;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/identity/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../src/identity/ports.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC3B,MAAM,IAAI,MAAM,CAAC;CAClB;AAED,oEAAoE;AACpE,MAAM,WAAW,WAAW;IAC1B,KAAK,IAAI,MAAM,CAAC;CACjB;AAED;+DAC+D;AAC/D,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;CACtC;AAED;wEACwE;AACxE,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CAClC;AAED;mEACmE;AACnE,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;CACrC"}

package/dist/identity/ports.js

@@ -0,0 +1,9 @@
+/**
+ * Effect ports — axiom 6: a host supplies its own effects. Nothing in src/
+ * reads a clock, randomness source, hash, path resolver, or environment
+ * variable; each law that needs an effect names the narrow power here and
+ * receives it from the caller. The engine call each port replaces is cited
+ * so parity stays checkable.
+ */
+export {};
+//# sourceMappingURL=ports.js.map

package/dist/identity/ports.js.map

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

package/dist/identity/product-state.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Product state-dir resolution — where a product brick keeps its per-user
+ * state on disk, as ONE law. Hoisted from the four bricks (apps, tools,
+ * agents, browser) that each hand-rolled this resolution and drifted;
+ * axiom 2 says a second place that computes a home directory is a bug, so
+ * the bricks import this instead.
+ *
+ * PURE laws only (axiom 6): nothing here reads `process.env` or the
+ * filesystem — the caller injects the env bag and the home directory, and
+ * gets a path string back. Creating the directory stays host-side.
+ */
+import type { EnvLike } from '../transport/auth.js';
+/**
+ * The env var that overrides a product's state dir: the product name in
+ * upper-snake between `AMALGM_` and `_DIR` — `browser` →
+ * `AMALGM_BROWSER_DIR`, `design-canvas` → `AMALGM_DESIGN_CANVAS_DIR`.
+ * A name with no usable characters cannot name an env var and is refused.
+ */
+export declare function productStateDirEnvVar(product: string): string;
+/** The five facts the resolver needs — env and homedir injected, never read. */
+export interface ProductStateDirInput {
+    /** The brick's name — only role: deriving {@link productStateDirEnvVar}. */
+    readonly product: string;
+    /** Which declared namespace the state lives under — one of {@link PRIMITIVE_DIRS}. */
+    readonly primitive: string;
+    /** An env-shaped bag of strings. The host passes process.env; tests pass literals. */
+    readonly env: EnvLike;
+    /** The amalgm root (the engine's `~/.amalgm`), resolved by the host. */
+    readonly homedir: string;
+    /** The user scope; absent falls to the sanitizer's `local`, as everywhere. */
+    readonly scope?: unknown;
+}
+/**
+ * The one resolution law, in precedence order:
+ *
+ *  1. `env[AMALGM_<PRODUCT>_DIR]` — the product-specific override, used
+ *     VERBATIM (an operator pointing state somewhere means exactly there);
+ *  2. `env.AMALGM_DIR` + `/<primitive>` — the shared override, one
+ *     namespace per primitive under it;
+ *  3. the ratified scoped layout — `<homedir>/users/<scope>/<primitive>`
+ *     via {@link scopedAmalgmDir} and {@link userPrimitiveRoot}, the same
+ *     grammar every other path in the kernel derives from.
+ *
+ * The primitive is validated against {@link PRIMITIVE_DIRS} on EVERY tier —
+ * an unknown primitive is a caller bug, and an env override must never
+ * mask it into a working path.
+ */
+export declare function resolveProductStateDir(input: ProductStateDirInput): string;
+//# sourceMappingURL=product-state.d.ts.map

package/dist/identity/product-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"product-state.d.ts","sourceRoot":"","sources":["../../src/identity/product-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAGpD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAU7D;AAED,gFAAgF;AAChF,MAAM,WAAW,oBAAoB;IACnC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sFAAsF;IACtF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sFAAsF;IACtF,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAU1E"}

package/dist/identity/product-state.js

@@ -0,0 +1,55 @@
+/**
+ * Product state-dir resolution — where a product brick keeps its per-user
+ * state on disk, as ONE law. Hoisted from the four bricks (apps, tools,
+ * agents, browser) that each hand-rolled this resolution and drifted;
+ * axiom 2 says a second place that computes a home directory is a bug, so
+ * the bricks import this instead.
+ *
+ * PURE laws only (axiom 6): nothing here reads `process.env` or the
+ * filesystem — the caller injects the env bag and the home directory, and
+ * gets a path string back. Creating the directory stays host-side.
+ */
+import { PRIMITIVE_DIRS, joinPathSegments, scopedAmalgmDir, userPrimitiveRoot } from './layout.js';
+/**
+ * The env var that overrides a product's state dir: the product name in
+ * upper-snake between `AMALGM_` and `_DIR` — `browser` →
+ * `AMALGM_BROWSER_DIR`, `design-canvas` → `AMALGM_DESIGN_CANVAS_DIR`.
+ * A name with no usable characters cannot name an env var and is refused.
+ */
+export function productStateDirEnvVar(product) {
+    const key = String(product || '')
+        .trim()
+        .replace(/[^A-Za-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .toUpperCase();
+    if (!key) {
+        throw new Error(`Unusable product name "${product}". Name the brick, e.g. "browser" -> AMALGM_BROWSER_DIR.`);
+    }
+    return `AMALGM_${key}_DIR`;
+}
+/**
+ * The one resolution law, in precedence order:
+ *
+ *  1. `env[AMALGM_<PRODUCT>_DIR]` — the product-specific override, used
+ *     VERBATIM (an operator pointing state somewhere means exactly there);
+ *  2. `env.AMALGM_DIR` + `/<primitive>` — the shared override, one
+ *     namespace per primitive under it;
+ *  3. the ratified scoped layout — `<homedir>/users/<scope>/<primitive>`
+ *     via {@link scopedAmalgmDir} and {@link userPrimitiveRoot}, the same
+ *     grammar every other path in the kernel derives from.
+ *
+ * The primitive is validated against {@link PRIMITIVE_DIRS} on EVERY tier —
+ * an unknown primitive is a caller bug, and an env override must never
+ * mask it into a working path.
+ */
+export function resolveProductStateDir(input) {
+    const { product, primitive, env, homedir, scope } = input;
+    const scopedFallback = userPrimitiveRoot(scopedAmalgmDir(homedir, scope), primitive);
+    const productOverride = env[productStateDirEnvVar(product)];
+    if (productOverride)
+        return productOverride;
+    if (env.AMALGM_DIR)
+        return joinPathSegments(env.AMALGM_DIR, primitive);
+    return scopedFallback;
+}
+//# sourceMappingURL=product-state.js.map

package/dist/identity/product-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"product-state.js","sourceRoot":"","sources":["../../src/identity/product-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEnG;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAe;IACnD,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC;SAC9B,IAAI,EAAE;SACN,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC;SAC9B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,WAAW,EAAE,CAAC;IACjB,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,0BAA0B,OAAO,0DAA0D,CAAC,CAAC;IAC/G,CAAC;IACD,OAAO,UAAU,GAAG,MAAM,CAAC;AAC7B,CAAC;AAgBD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAA2B;IAChE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IAC1D,MAAM,cAAc,GAAG,iBAAiB,CAAC,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC;IAErF,MAAM,eAAe,GAAG,GAAG,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5D,IAAI,eAAe;QAAE,OAAO,eAAe,CAAC;IAE5C,IAAI,GAAG,CAAC,UAAU;QAAE,OAAO,gBAAgB,CAAC,GAAG,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IAEvE,OAAO,cAAc,CAAC;AACxB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @amalgm/core — the Amalgm kernel SDK.
+ *
+ * Three modules, one membership test (PURPOSE.md): needed to boot,
+ * supervise, or route to an app, and can't itself be an app.
+ *
+ *   identity/     who this machine is: labels, layout, ids, auth records.
+ *   transport/    the pipe: auth boundary, one routing table, admission,
+ *                 event-rail ingress.
+ *   supervision/  the cascade: health contracts, restart policy, updater
+ *                 laws, service registration.
+ *
+ * Everything here is a pure contract or decision core; hosts inject their
+ * effects through the ports in `adapters/`.
+ */
+export * from './identity/index.js';
+export * from './transport/index.js';
+export * from './supervision/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * @amalgm/core — the Amalgm kernel SDK.
+ *
+ * Three modules, one membership test (PURPOSE.md): needed to boot,
+ * supervise, or route to an app, and can't itself be an app.
+ *
+ *   identity/     who this machine is: labels, layout, ids, auth records.
+ *   transport/    the pipe: auth boundary, one routing table, admission,
+ *                 event-rail ingress.
+ *   supervision/  the cascade: health contracts, restart policy, updater
+ *                 laws, service registration.
+ *
+ * Everything here is a pure contract or decision core; hosts inject their
+ * effects through the ports in `adapters/`.
+ */
+export * from './identity/index.js';
+export * from './transport/index.js';
+export * from './supervision/index.js';
+//# sourceMappingURL=index.js.map