@timurproko/a1 0.1.0 → 0.1.1-dev.10

package/dist/src/foundation/ui-components/surface.d.ts

@@ -0,0 +1,20 @@
+import { type ScrollbarGeometry } from "./scrollbar.js";
+import type { UiTheme } from "./theme.js";
+/**
+ * The chrome around a list: the rail down its right edge, and what it shows when
+ * there is nothing to list. Both are the same on any screen, so neither is a
+ * screen's to draw.
+ */
+/** Columns the rail occupies: its own, plus the gap before it. */
+export declare const RAIL_COLUMNS = 2;
+export interface RailOptions {
+    /** Rows at the top the rail does not run beside, such as a sticky header. */
+    readonly topInset?: number;
+}
+/** Draws the rail beside each row, padding the rows to a common width first. */
+export declare function withScrollbarRail(lines: readonly string[], geometry: ScrollbarGeometry | null, contentWidth: number, theme: UiTheme, options?: RailOptions): readonly string[];
+/**
+ * What a list shows instead of rows: a mark and a line, both quiet, sitting in
+ * the middle of the space the rows would have had.
+ */
+export declare function renderEmptyState(message: string, mark: string, height: number, width: number, theme: UiTheme): readonly string[];

package/dist/src/foundation/ui-components/surface.js

@@ -0,0 +1,38 @@
+import { isThumbRow } from "./scrollbar.js";
+import { displayWidth } from "./text.js";
+/**
+ * The chrome around a list: the rail down its right edge, and what it shows when
+ * there is nothing to list. Both are the same on any screen, so neither is a
+ * screen's to draw.
+ */
+/** Columns the rail occupies: its own, plus the gap before it. */
+export const RAIL_COLUMNS = 2;
+/** Draws the rail beside each row, padding the rows to a common width first. */
+export function withScrollbarRail(lines, geometry, contentWidth, theme, options = {}) {
+    const inset = options.topInset ?? 0;
+    return lines.map((line, offset) => {
+        const cell = offset < inset || geometry === null
+            ? " "
+            : isThumbRow(geometry, offset - inset) ? theme.fg("accent", "│") : theme.fg("dim", "│");
+        return `${pad(line, contentWidth)} ${cell}`;
+    });
+}
+/**
+ * What a list shows instead of rows: a mark and a line, both quiet, sitting in
+ * the middle of the space the rows would have had.
+ */
+export function renderEmptyState(message, mark, height, width, theme) {
+    const middle = Math.floor(height / 2);
+    return Array.from({ length: Math.max(0, height) }, (_line, index) => {
+        if (index === middle - 1)
+            return centre(theme.fg("muted", mark), mark, width);
+        return index === middle ? centre(theme.fg("muted", message), message, width) : "";
+    });
+}
+function centre(painted, raw, width) {
+    return `${" ".repeat(Math.max(0, Math.floor((width - displayWidth(raw)) / 2)))}${painted}`;
+}
+function pad(line, width) {
+    const visible = displayWidth(line);
+    return visible >= width ? line : line + " ".repeat(width - visible);
+}

package/dist/src/foundation/ui-components/text.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Display-width text handling. Terminals lay out by column, not by code unit,
+ * so measuring with `String.length` mis-sizes CJK, emoji, and combining marks,
+ * and counting styling escapes as visible width breaks every layout that uses
+ * colour.
+ */
+/** Removes styling sequences so only visible characters remain. */
+export declare function stripAnsi(text: string): string;
+/** Columns this text occupies once styling is removed. */
+export declare function displayWidth(text: string): number;
+/**
+ * Truncates to a column budget without splitting a grapheme. Styling sequences
+ * are carried through and a reset is appended when any style was opened, so a
+ * truncated row cannot leak colour into the rest of the line.
+ */
+export declare function truncateToWidth(text: string, maxWidth: number): string;
+/** Pads to an exact column count, truncating when the text is already wider. */
+export declare function padToWidth(text: string, width: number): string;
+/**
+ * A control that is present but cannot be used: the terminal own faint
+ * attribute over whatever colour it already carries, so it reads as half of what
+ * it would otherwise be in any theme.
+ */
+export declare function faint(text: string): string;

package/dist/src/foundation/ui-components/text.js

@@ -0,0 +1,123 @@
+/**
+ * Display-width text handling. Terminals lay out by column, not by code unit,
+ * so measuring with `String.length` mis-sizes CJK, emoji, and combining marks,
+ * and counting styling escapes as visible width breaks every layout that uses
+ * colour.
+ */
+const ANSI_PATTERN = /\[[0-9;:?]*[ -/]*[@-~]|\][^]*(?:|\\)|[@-Z\\-_]/g;
+const SEGMENTER = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+/** Removes styling sequences so only visible characters remain. */
+export function stripAnsi(text) {
+    return text.replace(ANSI_PATTERN, "");
+}
+function codePointWidth(codePoint) {
+    // Zero-width: combining marks, joiners, variation selectors, and format characters.
+    if (codePoint === 0x200d || codePoint === 0xfeff)
+        return 0;
+    if (codePoint >= 0x0300 && codePoint <= 0x036f)
+        return 0;
+    if (codePoint >= 0x200b && codePoint <= 0x200f)
+        return 0;
+    if (codePoint >= 0xfe00 && codePoint <= 0xfe0f)
+        return 0;
+    if (codePoint >= 0x20d0 && codePoint <= 0x20f0)
+        return 0;
+    if (codePoint >= 0x1ab0 && codePoint <= 0x1aff)
+        return 0;
+    if (codePoint >= 0x1dc0 && codePoint <= 0x1dff)
+        return 0;
+    if (codePoint >= 0xe0100 && codePoint <= 0xe01ef)
+        return 0;
+    // Wide: CJK, Hangul, fullwidth forms, and the emoji planes terminals render double-width.
+    if (codePoint >= 0x1100 && codePoint <= 0x115f)
+        return 2;
+    if (codePoint >= 0x2e80 && codePoint <= 0xa4cf && codePoint !== 0x303f)
+        return 2;
+    if (codePoint >= 0xac00 && codePoint <= 0xd7a3)
+        return 2;
+    if (codePoint >= 0xf900 && codePoint <= 0xfaff)
+        return 2;
+    if (codePoint >= 0xfe30 && codePoint <= 0xfe6f)
+        return 2;
+    if (codePoint >= 0xff00 && codePoint <= 0xff60)
+        return 2;
+    if (codePoint >= 0xffe0 && codePoint <= 0xffe6)
+        return 2;
+    if (codePoint >= 0x1f300 && codePoint <= 0x1f64f)
+        return 2;
+    if (codePoint >= 0x1f900 && codePoint <= 0x1f9ff)
+        return 2;
+    if (codePoint >= 0x20000 && codePoint <= 0x3fffd)
+        return 2;
+    // Control characters occupy nothing.
+    if (codePoint < 0x20 || (codePoint >= 0x7f && codePoint < 0xa0))
+        return 0;
+    return 1;
+}
+/** Width of one grapheme cluster: the widest code point it contains, marks excluded. */
+function graphemeWidth(grapheme) {
+    let width = 0;
+    for (const character of grapheme) {
+        width = Math.max(width, codePointWidth(character.codePointAt(0) ?? 0));
+    }
+    return width;
+}
+/** Columns this text occupies once styling is removed. */
+export function displayWidth(text) {
+    let width = 0;
+    for (const { segment } of SEGMENTER.segment(stripAnsi(text)))
+        width += graphemeWidth(segment);
+    return width;
+}
+/**
+ * Truncates to a column budget without splitting a grapheme. Styling sequences
+ * are carried through and a reset is appended when any style was opened, so a
+ * truncated row cannot leak colour into the rest of the line.
+ */
+export function truncateToWidth(text, maxWidth) {
+    if (maxWidth <= 0)
+        return "";
+    if (displayWidth(text) <= maxWidth)
+        return text;
+    let out = "";
+    let width = 0;
+    let styled = false;
+    let index = 0;
+    while (index < text.length) {
+        ANSI_PATTERN.lastIndex = index;
+        const match = ANSI_PATTERN.exec(text);
+        if (match && match.index === index) {
+            out += match[0];
+            styled = true;
+            index += match[0].length;
+            continue;
+        }
+        const nextEscape = match ? match.index : text.length;
+        for (const { segment } of SEGMENTER.segment(text.slice(index, nextEscape))) {
+            const segmentWidth = graphemeWidth(segment);
+            if (width + segmentWidth > maxWidth)
+                return styled ? `${out}` : out;
+            out += segment;
+            width += segmentWidth;
+        }
+        index = nextEscape;
+    }
+    return styled ? `${out}` : out;
+}
+/** Pads to an exact column count, truncating when the text is already wider. */
+export function padToWidth(text, width) {
+    if (width <= 0)
+        return "";
+    const current = displayWidth(text);
+    if (current > width)
+        return truncateToWidth(text, width);
+    return text + " ".repeat(width - current);
+}
+/**
+ * A control that is present but cannot be used: the terminal own faint
+ * attribute over whatever colour it already carries, so it reads as half of what
+ * it would otherwise be in any theme.
+ */
+export function faint(text) {
+    return `${text}`;
+}

package/dist/src/foundation/ui-components/theme.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Colour as a port, so a screen can be rendered and asserted without a terminal
+ * or a theme, and so the component layer never imports a Pi adapter.
+ */
+export type UiThemeToken = "accent" | "text" | "muted" | "dim" | "border" | "error";
+export interface UiTheme {
+    fg(token: UiThemeToken, text: string): string;
+    bold(text: string): string;
+    /**
+     * The terminal's own foreground, left unpainted. What a list's own text is:
+     * a theme built for a light background would otherwise write near-black rows
+     * into a dark terminal, which is how the engine leaves its lists too.
+     */
+    plain(text: string): string;
+    /** Inverted styling for the active row of a floating surface. */
+    highlight(text: string): string;
+    /** A control that is present but cannot act: quieter than quiet text. */
+    disabled(text: string): string;
+    /** Background for a floating surface, so it reads as above the content. */
+    panel(text: string): string;
+}
+/** Renders every token as plain text. What tests assert against. */
+export declare const PLAIN_THEME: UiTheme;

package/dist/src/foundation/ui-components/theme.js

@@ -0,0 +1,13 @@
+/**
+ * Colour as a port, so a screen can be rendered and asserted without a terminal
+ * or a theme, and so the component layer never imports a Pi adapter.
+ */
+/** Renders every token as plain text. What tests assert against. */
+export const PLAIN_THEME = Object.freeze({
+    fg: (_token, text) => text,
+    bold: (text) => text,
+    plain: (text) => text,
+    highlight: (text) => text,
+    disabled: (text) => text,
+    panel: (text) => text,
+});

package/dist/src/foundation/ui-components/value-menu.d.ts

@@ -0,0 +1,41 @@
+import type { UiTheme } from "./theme.js";
+/**
+ * The menu a value opens: anchored to the row it was opened from, marking what
+ * is in effect, highlighting nothing until something is picked, and flipping
+ * above its anchor only when it would otherwise run off the bottom.
+ */
+export interface ValueMenuState {
+    /** Values offered, as they should read. */
+    readonly choices: readonly string[];
+    /** The value in effect, marked rather than highlighted. */
+    readonly current: string | null;
+    /** The entry picked by a key or the pointer, or -1 while none is. */
+    readonly index: number;
+}
+export interface ValueMenuAnchor {
+    /** Row the menu was opened from, which it keeps even as the selection moves. */
+    readonly screenRow: number;
+    /** Column the values start at. */
+    readonly valueColumn: number;
+}
+/** Where a menu sits on screen, for reading a pointer against it. */
+export interface ValueMenuFrame {
+    readonly top: number;
+    readonly column: number;
+    readonly width: number;
+    readonly rows: number;
+}
+export interface ValueMenuLayout {
+    /** Rows available above the footer. */
+    readonly bodyHeight: number;
+    /** Full surface width, so the menu stays inside it. */
+    readonly surfaceWidth: number;
+    /** Columns reserved at the right edge, such as a scrollbar rail. */
+    readonly reservedRight: number;
+}
+/** Where the menu is placed: below its anchor where there is room, else above. */
+export declare function valueMenuFrame(state: ValueMenuState, anchor: ValueMenuAnchor, layout: ValueMenuLayout): ValueMenuFrame;
+/** Draws the menu over the rows behind it, leaving them otherwise untouched. */
+export declare function renderValueMenu(lines: readonly string[], state: ValueMenuState, frame: ValueMenuFrame, theme: UiTheme): readonly string[];
+/** Whether a pointer report lands inside the menu rather than behind it. */
+export declare function menuRowAt(frame: ValueMenuFrame, row: number, column: number): number | null;

package/dist/src/foundation/ui-components/value-menu.js

@@ -0,0 +1,33 @@
+import { overlaySpan } from "./spans.js";
+import { displayWidth, padToWidth } from "./text.js";
+/** Where the menu is placed: below its anchor where there is room, else above. */
+export function valueMenuFrame(state, anchor, layout) {
+    const below = anchor.screenRow + 1;
+    const top = below + state.choices.length <= layout.bodyHeight
+        ? below
+        : Math.max(0, anchor.screenRow - state.choices.length);
+    const width = Math.max(...state.choices.map(choice => displayWidth(choice) + 4), 6);
+    const column = Math.min(anchor.valueColumn, Math.max(0, layout.surfaceWidth - width - layout.reservedRight));
+    return { top, column, width, rows: state.choices.length };
+}
+/** Draws the menu over the rows behind it, leaving them otherwise untouched. */
+export function renderValueMenu(lines, state, frame, theme) {
+    const output = [...lines];
+    state.choices.forEach((choice, index) => {
+        const target = frame.top + index;
+        if (target < 0 || target >= output.length)
+            return;
+        const mark = choice === state.current ? "✓ " : "  ";
+        const text = padToWidth(`${mark}${choice} `, frame.width);
+        const painted = index === state.index ? theme.highlight(text) : theme.panel(text);
+        output[target] = overlaySpan(output[target] ?? "", frame.column, frame.column + frame.width, painted);
+    });
+    return output;
+}
+/** Whether a pointer report lands inside the menu rather than behind it. */
+export function menuRowAt(frame, row, column) {
+    const at = row - frame.top;
+    if (at < 0 || at >= frame.rows)
+        return null;
+    return column > frame.column && column <= frame.column + frame.width ? at : null;
+}

package/dist/src/foundation/workspace-contracts/index.d.ts

@@ -1,3 +1,2 @@
 export * from "./model.js";
 export * from "./validation.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/src/foundation/workspace-contracts/index.js

@@ -1,3 +1,2 @@
 export * from "./model.js";
 export * from "./validation.js";
-//# sourceMappingURL=index.js.map

package/dist/src/foundation/workspace-contracts/model.d.ts

@@ -246,4 +246,3 @@ export interface ComposedRecoveryAuthority {
     readonly streamPosition: number;
 }
 export type AgentRecoveryAuthority = StructuredRecoveryAuthority | ComposedRecoveryAuthority;
-//# sourceMappingURL=model.d.ts.map

package/dist/src/foundation/workspace-contracts/model.js

@@ -1,3 +1,2 @@
 export const WORKSPACE_CONTRACT_VERSION = 1;
 export const NATIVE_HOST_PROTOCOL_VERSION = 1;
-//# sourceMappingURL=model.js.map

package/dist/src/foundation/workspace-contracts/validation.d.ts

@@ -11,4 +11,3 @@ export declare function assertTerminalTopologySnapshot(topology: TerminalTopolog
 export declare function assertNativeHostCommand(command: NativeHostCommand): void;
 export declare function assertRecoveryAuthority(authority: AgentRecoveryAuthority): void;
 export declare function assertTerminalSessionLaunch(session: TerminalSessionLaunch): void;
-//# sourceMappingURL=validation.d.ts.map

package/dist/src/foundation/workspace-contracts/validation.js

@@ -333,4 +333,3 @@ function assertIntegerInRange(value, minimum, maximum, name) {
         throw new RangeError(`${name} must be an integer from ${minimum} to ${maximum}`);
     }
 }
-//# sourceMappingURL=validation.js.map

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

@@ -0,0 +1,37 @@
+declare const ENVIRONMENT_KEYS: readonly ["certificationTarball", "configDir", "dataDir", "databasePath", "developmentInstanceId", "developmentRoot", "endpoint", "fixture", "fixtureInput", "fixtureToken", "inputAcknowledgement", "internalPackaging", "launchArgumentsJson", "launchProfile", "nativePi", "paneId", "piParityIntentionalMutation", "piPortRoot", "piSourceLedgerPath", "piSourceScanRoot", "probeTrace", "processGuardianPath", "profileHome", "protocolVersion", "releaseDigest", "releaseId", "releaseRoot", "releaseRunnerLabel", "runtimeDir", "structuredFlowLimits", "terminalArgumentsJson", "terminalExecutable", "terminalSessionId"];
+declare const FILESYSTEM_KEYS: readonly ["slug", "windowsDirectory", "unixDirectory", "temporaryPrefix"];
+declare const STATE_KEYS: readonly ["windowsControlDirectory", "unixControlDirectory", "developmentDirectory", "piAgentProfile", "piVanillaProfile", "piSandboxProfile"];
+declare const ENDPOINT_KEYS: readonly ["windowsPipeStem", "unixSocketFilename", "metadataFilename", "supervisorLogFilename", "databaseFilename"];
+declare const MANIFEST_KEYS: readonly ["releaseFilename", "packageFilename"];
+declare const PROTOCOL_KEYS: readonly ["namespace", "controlEnvelope", "supervisorSchema", "nativeHostSchema", "structuredAgentSchema", "controlStoreSchema", "releaseCohortSchema", "updateJournalSchema"];
+declare const EVIDENCE_KEYS: readonly ["nativeSpikeSchema", "terminalProvenanceSchema", "terminalProofSchema", "stableReleaseSchema", "previewReleaseSchema", "releaseCertificationSchema", "previewPlatformVerdictSchema", "piSourceLedgerSchema", "piComponentParitySchema", "piEventFrameParitySchema"];
+declare const ARTIFACT_KEYS: readonly ["cliEntry", "supervisorEntry", "guardianEntry", "uiEntry", "nativeExecutable", "nativeCrate", "processGuardianExecutable", "releaseTarballStem", "diagnosticStem"];
+type StringRecord<Keys extends readonly string[]> = {
+    readonly [Key in Keys[number]]: string;
+};
+export interface ProductIdentity {
+    readonly schema: string;
+    readonly displayName: string;
+    readonly commandName: string;
+    readonly packageName: string;
+    readonly filesystem: StringRecord<typeof FILESYSTEM_KEYS>;
+    readonly environment: StringRecord<typeof ENVIRONMENT_KEYS>;
+    readonly state: StringRecord<typeof STATE_KEYS>;
+    readonly endpoint: StringRecord<typeof ENDPOINT_KEYS>;
+    readonly manifest: StringRecord<typeof MANIFEST_KEYS>;
+    readonly protocol: StringRecord<typeof PROTOCOL_KEYS>;
+    readonly evidence: StringRecord<typeof EVIDENCE_KEYS>;
+    readonly artifacts: StringRecord<typeof ARTIFACT_KEYS>;
+}
+export declare function validateProductIdentity(value: unknown): ProductIdentity;
+export interface ProductIdentityText {
+    readonly displayName: string;
+    readonly commandName: string;
+    readonly packageName: string;
+    readonly diagnostic: (message: string) => string;
+    readonly usage: (forms: readonly string[]) => string;
+}
+export declare function createProductIdentityText(identity: Pick<ProductIdentity, "displayName" | "commandName" | "packageName">): ProductIdentityText;
+export declare const PRODUCT_IDENTITY: ProductIdentity;
+export declare const PRODUCT_TEXT: ProductIdentityText;
+export {};

package/dist/src/product-identity.js

@@ -0,0 +1,150 @@
+import rawIdentity from "./product-identity.json" with { type: "json" };
+const ENVIRONMENT_KEYS = [
+    "certificationTarball",
+    "configDir",
+    "dataDir",
+    "databasePath",
+    "developmentInstanceId",
+    "developmentRoot",
+    "endpoint",
+    "fixture",
+    "fixtureInput",
+    "fixtureToken",
+    "inputAcknowledgement",
+    "internalPackaging",
+    "launchArgumentsJson",
+    "launchProfile",
+    "nativePi",
+    "paneId",
+    "piParityIntentionalMutation",
+    "piPortRoot",
+    "piSourceLedgerPath",
+    "piSourceScanRoot",
+    "probeTrace",
+    "processGuardianPath",
+    "profileHome",
+    "protocolVersion",
+    "releaseDigest",
+    "releaseId",
+    "releaseRoot",
+    "releaseRunnerLabel",
+    "runtimeDir",
+    "structuredFlowLimits",
+    "terminalArgumentsJson",
+    "terminalExecutable",
+    "terminalSessionId",
+];
+const FILESYSTEM_KEYS = ["slug", "windowsDirectory", "unixDirectory", "temporaryPrefix"];
+const STATE_KEYS = ["windowsControlDirectory", "unixControlDirectory", "developmentDirectory", "piAgentProfile", "piVanillaProfile", "piSandboxProfile"];
+const ENDPOINT_KEYS = ["windowsPipeStem", "unixSocketFilename", "metadataFilename", "supervisorLogFilename", "databaseFilename"];
+const MANIFEST_KEYS = ["releaseFilename", "packageFilename"];
+const PROTOCOL_KEYS = ["namespace", "controlEnvelope", "supervisorSchema", "nativeHostSchema", "structuredAgentSchema", "controlStoreSchema", "releaseCohortSchema", "updateJournalSchema"];
+const EVIDENCE_KEYS = ["nativeSpikeSchema", "terminalProvenanceSchema", "terminalProofSchema", "stableReleaseSchema", "previewReleaseSchema", "releaseCertificationSchema", "previewPlatformVerdictSchema", "piSourceLedgerSchema", "piComponentParitySchema", "piEventFrameParitySchema"];
+const ARTIFACT_KEYS = ["cliEntry", "supervisorEntry", "guardianEntry", "uiEntry", "nativeExecutable", "nativeCrate", "processGuardianExecutable", "releaseTarballStem", "diagnosticStem"];
+const ROOT_KEYS = ["schema", "displayName", "commandName", "packageName", "filesystem", "environment", "state", "endpoint", "manifest", "protocol", "evidence", "artifacts"];
+export function validateProductIdentity(value) {
+    const root = exactObject(value, ROOT_KEYS, "product identity");
+    const schema = stringValue(root.schema, "product identity schema");
+    const displayName = stringValue(root.displayName, "product display name");
+    const commandName = stringValue(root.commandName, "product command name");
+    const packageName = stringValue(root.packageName, "product package name");
+    const filesystem = stringObject(root.filesystem, FILESYSTEM_KEYS, "filesystem identity");
+    const environment = stringObject(root.environment, ENVIRONMENT_KEYS, "environment identity");
+    const state = stringObject(root.state, STATE_KEYS, "state identity");
+    const endpoint = stringObject(root.endpoint, ENDPOINT_KEYS, "endpoint identity");
+    const manifest = stringObject(root.manifest, MANIFEST_KEYS, "manifest identity");
+    const protocol = stringObject(root.protocol, PROTOCOL_KEYS, "protocol identity");
+    const evidence = stringObject(root.evidence, EVIDENCE_KEYS, "evidence identity");
+    const artifacts = stringObject(root.artifacts, ARTIFACT_KEYS, "artifact identity");
+    if (!/^[a-z][a-z0-9-]*$/.test(commandName))
+        throw new TypeError("product command name must be a lowercase command slug");
+    if (!/^@[a-z0-9-]+\/[a-z0-9-]+$/.test(packageName))
+        throw new TypeError("product package name must be a lowercase scoped npm package");
+    if (displayName.trim() !== displayName || displayName.length === 0)
+        throw new TypeError("product display name must be non-empty without surrounding whitespace");
+    if (schema !== `${commandName}-product-identity-v1`)
+        throw new TypeError("product identity schema must derive from the command name");
+    if (filesystem.slug !== commandName || filesystem.unixDirectory !== filesystem.slug || filesystem.windowsDirectory !== displayName) {
+        throw new TypeError("product filesystem identity must derive from display and command names");
+    }
+    if (filesystem.temporaryPrefix !== `${filesystem.slug}-`)
+        throw new TypeError("product temporary prefix must derive from the filesystem slug");
+    if (state.windowsControlDirectory !== filesystem.windowsDirectory || state.unixControlDirectory !== filesystem.unixDirectory) {
+        throw new TypeError("product state directories must match the filesystem identity");
+    }
+    if (endpoint.windowsPipeStem !== filesystem.slug)
+        throw new TypeError("product endpoint stem must match the filesystem slug");
+    if (protocol.namespace !== commandName)
+        throw new TypeError("product protocol namespace must match the command name");
+    if (artifacts.diagnosticStem !== filesystem.slug)
+        throw new TypeError("product diagnostic stem must match the filesystem slug");
+    const environmentPrefix = `${commandName.toUpperCase()}_`;
+    const environmentValues = Object.values(environment);
+    if (new Set(environmentValues).size !== environmentValues.length)
+        throw new TypeError("product environment keys must be unique");
+    for (const key of environmentValues) {
+        if (!key.startsWith(environmentPrefix) || !/^[A-Z][A-Z0-9_]+$/.test(key)) {
+            throw new TypeError(`product environment key must use ${environmentPrefix}: ${key}`);
+        }
+    }
+    for (const [name, identifier] of Object.entries(protocol)) {
+        if (name !== "namespace" && !identifier.startsWith(`${protocol.namespace}-`)) {
+            throw new TypeError(`product protocol identifier must use ${protocol.namespace}: ${identifier}`);
+        }
+    }
+    for (const identifier of Object.values(evidence)) {
+        if (!identifier.startsWith(`${protocol.namespace}-`))
+            throw new TypeError(`product evidence identifier must use ${protocol.namespace}: ${identifier}`);
+    }
+    return deepFreeze({
+        schema,
+        displayName,
+        commandName,
+        packageName,
+        filesystem,
+        environment,
+        state,
+        endpoint,
+        manifest,
+        protocol,
+        evidence,
+        artifacts,
+    });
+}
+export function createProductIdentityText(identity) {
+    return Object.freeze({
+        displayName: identity.displayName,
+        commandName: identity.commandName,
+        packageName: identity.packageName,
+        diagnostic: (message) => `${identity.displayName} ${message}`,
+        usage: (forms) => `Usage: ${forms.map(form => `${identity.commandName}${form ? ` ${form}` : ""}`).join(" | ")}`,
+    });
+}
+export const PRODUCT_IDENTITY = validateProductIdentity(rawIdentity);
+export const PRODUCT_TEXT = createProductIdentityText(PRODUCT_IDENTITY);
+function exactObject(value, keys, name) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new TypeError(`${name} must be an object`);
+    const actualKeys = Object.keys(value).sort();
+    const expectedKeys = [...keys].sort();
+    if (actualKeys.length !== expectedKeys.length || actualKeys.some((key, index) => key !== expectedKeys[index])) {
+        throw new TypeError(`${name} must contain exactly: ${expectedKeys.join(", ")}`);
+    }
+    return value;
+}
+function stringObject(value, keys, name) {
+    const object = exactObject(value, keys, name);
+    return Object.fromEntries(keys.map((key) => [key, stringValue(object[key], `${name}.${key}`)]));
+}
+function stringValue(value, name) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new TypeError(`${name} must be a non-empty string`);
+    return value;
+}
+function deepFreeze(value) {
+    if (typeof value !== "object" || value === null || Object.isFrozen(value))
+        return value;
+    for (const child of Object.values(value))
+        deepFreeze(child);
+    return Object.freeze(value);
+}

package/dist/src/product-identity.json

@@ -0,0 +1,99 @@
+{
+    "schema": "a1-product-identity-v1",
+    "displayName": "A1",
+    "commandName": "a1",
+    "packageName": "@timurproko/a1",
+    "filesystem": {
+        "slug": "a1",
+        "windowsDirectory": "A1",
+        "unixDirectory": "a1",
+        "temporaryPrefix": "a1-"
+    },
+    "environment": {
+        "certificationTarball": "A1_CERTIFICATION_TARBALL",
+        "configDir": "A1_CONFIG_DIR",
+        "dataDir": "A1_DATA_DIR",
+        "databasePath": "A1_DATABASE_PATH",
+        "developmentInstanceId": "A1_DEV_INSTANCE_ID",
+        "developmentRoot": "A1_DEV_ROOT",
+        "endpoint": "A1_ENDPOINT",
+        "fixture": "A1_FIXTURE",
+        "fixtureInput": "A1_FIXTURE_INPUT",
+        "fixtureToken": "A1_FIXTURE_TOKEN",
+        "inputAcknowledgement": "A1_INPUT_ACK",
+        "internalPackaging": "A1_INTERNAL_PACKAGING",
+        "launchArgumentsJson": "A1_LAUNCH_ARGUMENTS_JSON",
+        "launchProfile": "A1_LAUNCH_PROFILE",
+        "nativePi": "A1_NATIVE_PI",
+        "paneId": "A1_PANE_ID",
+        "piParityIntentionalMutation": "A1_PI_PARITY_INTENTIONAL_MUTATION",
+        "piPortRoot": "A1_PI_PORT_ROOT",
+        "piSourceLedgerPath": "A1_PI_SOURCE_LEDGER_PATH",
+        "piSourceScanRoot": "A1_PI_SOURCE_SCAN_ROOT",
+        "probeTrace": "A1_PROBE_TRACE",
+        "processGuardianPath": "A1_PROCESS_GUARDIAN_PATH",
+        "profileHome": "A1_PROFILE_HOME",
+        "protocolVersion": "A1_PROTOCOL_VERSION",
+        "releaseDigest": "A1_RELEASE_DIGEST",
+        "releaseId": "A1_RELEASE_ID",
+        "releaseRoot": "A1_RELEASE_ROOT",
+        "releaseRunnerLabel": "A1_RELEASE_RUNNER_LABEL",
+        "runtimeDir": "A1_RUNTIME_DIR",
+        "structuredFlowLimits": "A1_STRUCTURED_FLOW_LIMITS",
+        "terminalArgumentsJson": "A1_TERMINAL_ARGUMENTS_JSON",
+        "terminalExecutable": "A1_TERMINAL_EXECUTABLE",
+        "terminalSessionId": "A1_TERMINAL_SESSION_ID"
+    },
+    "state": {
+        "windowsControlDirectory": "A1",
+        "unixControlDirectory": "a1",
+        "developmentDirectory": "a1-development",
+        "piAgentProfile": ".a1/agent",
+        "piVanillaProfile": ".pi/agent",
+        "piSandboxProfile": ".a1/sandbox"
+    },
+    "endpoint": {
+        "windowsPipeStem": "a1",
+        "unixSocketFilename": "supervisor.sock",
+        "metadataFilename": "supervisor.json",
+        "supervisorLogFilename": "supervisor.log",
+        "databaseFilename": "control.sqlite3"
+    },
+    "manifest": {
+        "releaseFilename": ".a1-release.json",
+        "packageFilename": "package.json"
+    },
+    "protocol": {
+        "namespace": "a1",
+        "controlEnvelope": "a1-control-envelope",
+        "supervisorSchema": "a1-supervisor-v1",
+        "nativeHostSchema": "a1-native-host-v1",
+        "structuredAgentSchema": "a1-structured-agent-v1",
+        "controlStoreSchema": "a1-control-store-v1",
+        "releaseCohortSchema": "a1-release-cohort-v1",
+        "updateJournalSchema": "a1-update-journal-v1"
+    },
+    "evidence": {
+        "nativeSpikeSchema": "a1-native-host-spike-evidence-v1",
+        "terminalProvenanceSchema": "a1-terminal-host-provenance-v1",
+        "terminalProofSchema": "a1-terminal-host-proof-v1",
+        "stableReleaseSchema": "a1-stable-release-v1",
+        "previewReleaseSchema": "a1-preview-release-v1",
+        "releaseCertificationSchema": "a1-release-certification-v1",
+        "previewPlatformVerdictSchema": "a1-development-preview-platform-verdict-v2",
+        "piSourceLedgerSchema": "a1-pinned-pi-source-port-ledger-v1",
+        "piComponentParitySchema": "a1-pi-static-component-parity-v1",
+        "piEventFrameParitySchema": "a1-pi-event-frame-parity-v1"
+    },
+    "artifacts": {
+        "cliEntry": "bin/cli.js",
+        "supervisorEntry": "bin/supervisor.js",
+        "guardianEntry": "bin/guardian.js",
+        "uiEntry": "bin/ui.js",
+        "nativeExecutable": "terminal-host",
+        "nativeCrate": "terminal-host",
+        "processGuardianExecutable": "process-guardian",
+        "releaseTarballStem": "timurproko-a1",
+        "diagnosticStem": "a1"
+    }
+}