@stateforge-labs/herdr-sdk 0.0.0-stage → 0.3.0

package/dist/core/wire.js

@@ -0,0 +1,199 @@
+// Role: the herdr-core wire: NDJSON JSON-RPC 2.0 codec, message parsers, the socket path rule and the backoff step.
+// Informs HERDR-ADR-0020 (the herdr-core client); ported from the desktop work in herdr-plugins.
+import { StringDecoder } from 'node:string_decoder';
+import { join } from 'node:path';
+import { err, isErr, isOk, must, ok } from './kernel.js';
+import { brand } from './kernel.js';
+import { parseCount } from './kernel.js';
+import { duration } from './kernel.js';
+import { parseNonEmptyText, parseText } from './kernel.js';
+import { isFields, isNumber, isString } from './kernel.js';
+import { EMPTY_TEXT, HC_BACKOFF_MAX_DOUBLINGS, HC_JSONRPC_VERSION, HC_LINE_SEPARATOR, ParseFailureKind, HcField, HcKind, HcNotificationMethod, UTF8 } from './constants.js';
+import { HC_LINE_CAP, HC_DEFAULT_SESSION, HC_RUNTIME_ENV, HC_RUN_ROOT, HC_SESSION_ENV, HC_SOCKET_ENV, HC_SOCKET_FOLDER, HC_SOCKET_SUFFIX } from './constants.js';
+const NOT_A_ROW = { kind: ParseFailureKind.NotARow };
+const NO_DATA = must(parseHcPayload({}));
+export function parseHcPayload(input) {
+    return isFields(input) ? ok(brand(input)) : err(NOT_A_ROW);
+}
+export function parseHcParams(input) {
+    return isFields(input) ? ok(brand(input)) : err(NOT_A_ROW);
+}
+export function parseHcTransport(input) {
+    const text = parseNonEmptyText(input);
+    return isErr(text) ? text : ok(brand(text.value.trim().toLowerCase()));
+}
+export function parseWireChunk(input) {
+    return Buffer.isBuffer(input) ? ok(brand(input)) : err(NOT_A_ROW);
+}
+export function parseWireLine(input) {
+    const text = parseText(input);
+    return isErr(text) ? text : ok(brand(text.value));
+}
+export function parseSocketPath(input) {
+    const text = parseNonEmptyText(input);
+    return isErr(text) ? text : ok(brand(text.value));
+}
+export function parseHcCallId(input) {
+    const count = parseCount(input);
+    return isErr(count) ? count : ok(brand(count.value));
+}
+export function parseRpcCode(input) {
+    if (!isNumber(input)) {
+        return err({ kind: ParseFailureKind.NotANumber });
+    }
+    return Number.isInteger(input) ? ok(brand(input)) : err({ kind: ParseFailureKind.NotAnInteger });
+}
+export function encodeHcCoreRequest(id, method, params) {
+    return must(parseWireLine(JSON.stringify({ [HcField.JsonRpc]: HC_JSONRPC_VERSION, [HcField.Id]: id, [HcField.Method]: method, [HcField.Params]: params }) + HC_LINE_SEPARATOR));
+}
+export class HcCoreLines {
+    decoder = new StringDecoder(UTF8);
+    overrun;
+    cap;
+    rest = EMPTY_TEXT;
+    constructor(overrun = () => undefined, cap = HC_LINE_CAP) {
+        this.overrun = overrun;
+        this.cap = cap;
+    }
+    feed(chunk) {
+        const fresh = this.decoder.write(chunk);
+        const cut = fresh.lastIndexOf(HC_LINE_SEPARATOR);
+        const text = this.rest + (cut < 0 ? fresh : fresh.slice(0, cut));
+        if (text.length > this.cap) {
+            this.rest = EMPTY_TEXT;
+            this.overrun();
+            return [];
+        }
+        if (cut < 0) {
+            this.rest = must(parseText(text));
+            return [];
+        }
+        this.rest = must(parseText(fresh.slice(cut + 1)));
+        const found = [];
+        for (const line of text.split(HC_LINE_SEPARATOR)) {
+            try {
+                const parsed = parseHcPayload(JSON.parse(line));
+                if (isOk(parsed)) {
+                    found.push(parsed.value);
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        return found;
+    }
+}
+export function hcCoreSocketPath() {
+    const direct = parseSocketPath(process.env[HC_SOCKET_ENV]);
+    if (isOk(direct)) {
+        return direct.value;
+    }
+    const runtime = parseNonEmptyText(process.env[HC_RUNTIME_ENV]);
+    const root = isOk(runtime) ? runtime.value : join(HC_RUN_ROOT, String(process.getuid?.() ?? 0));
+    const session = parseNonEmptyText(process.env[HC_SESSION_ENV]);
+    const name = isOk(session) ? session.value : HC_DEFAULT_SESSION;
+    return must(parseSocketPath(join(root, HC_SOCKET_FOLDER, name + HC_SOCKET_SUFFIX)));
+}
+export function nextBackoff(failures, base, cap) {
+    return duration(Math.min(cap, base * 2 ** Math.min(failures, HC_BACKOFF_MAX_DOUBLINGS)));
+}
+export function parseHcSnapshot(input) {
+    if (!isFields(input)) {
+        return err(NOT_A_ROW);
+    }
+    const seq = parseCount(input[HcField.Seq]);
+    const rows = input[HcField.Terminals];
+    if (isErr(seq) || !Array.isArray(rows)) {
+        return err(NOT_A_ROW);
+    }
+    const terminals = rows.flatMap((row) => {
+        const payload = parseHcPayload(row);
+        return isOk(payload) ? [payload.value] : [];
+    });
+    return ok({ seq: seq.value, terminals });
+}
+export function parseHcCoreHello(input) {
+    if (!isFields(input)) {
+        return err(NOT_A_ROW);
+    }
+    const generation = parseCount(input[HcField.Generation]);
+    const version = parseText(input[HcField.Version]);
+    const names = input[HcField.Methods];
+    if (isErr(generation) || isErr(version) || !Array.isArray(names)) {
+        return err(NOT_A_ROW);
+    }
+    const methods = names.flatMap((name) => {
+        const method = parseNonEmptyText(name);
+        return isOk(method) ? [method.value] : [];
+    });
+    return ok({ version: version.value, methods, generation: generation.value });
+}
+export function parseHcFault(id, error) {
+    if (!isFields(error)) {
+        return err(NOT_A_ROW);
+    }
+    const code = parseRpcCode(error[HcField.Code]);
+    const message = parseText(error[HcField.Message]);
+    const data = error[HcField.Data];
+    const reason = parseText(isFields(data) ? data[HcField.Kind] : EMPTY_TEXT);
+    if (isErr(code) || isErr(message) || isErr(reason)) {
+        return err(NOT_A_ROW);
+    }
+    return ok({ kind: HcKind.Fault, id, code: code.value, reason: reason.value, message: message.value });
+}
+export function parseHcReply(input) {
+    if (!isFields(input)) {
+        return err(NOT_A_ROW);
+    }
+    const id = parseHcCallId(input[HcField.Id]);
+    if (isErr(id)) {
+        return id;
+    }
+    if (Object.hasOwn(input, HcField.Error)) {
+        return parseHcFault(id.value, input[HcField.Error]);
+    }
+    if (!Object.hasOwn(input, HcField.Result)) {
+        return err(NOT_A_ROW);
+    }
+    const result = parseHcPayload(input[HcField.Result]);
+    return ok(isOk(result) ? { kind: HcKind.Reply, id: id.value, result: result.value } : { kind: HcKind.Odd, id: id.value });
+}
+export function parseHcEvent(input) {
+    if (!isFields(input)) {
+        return err(NOT_A_ROW);
+    }
+    const seq = parseCount(input[HcField.Seq]);
+    const type = parseNonEmptyText(input[HcField.Type]);
+    const terminal = parseNonEmptyText(input[HcField.Terminal]);
+    const data = parseHcPayload(input[HcField.Data]);
+    if (isErr(seq) || isErr(type)) {
+        return err(NOT_A_ROW);
+    }
+    return ok({ kind: HcKind.Event, seq: seq.value, terminal: isOk(terminal) ? terminal.value : null, type: type.value, data: isOk(data) ? data.value : NO_DATA });
+}
+export function parseHcHeartbeat(input) {
+    const seq = parseCount(isFields(input) ? input[HcField.Seq] : undefined);
+    return isErr(seq) ? seq : ok({ kind: HcKind.Heartbeat, seq: seq.value });
+}
+export function parseHcMissed(input) {
+    const snapshot = parseHcSnapshot(input);
+    return isErr(snapshot) ? snapshot : ok({ kind: HcKind.Missed, snapshot: snapshot.value });
+}
+const NOTIFICATIONS = {
+    [HcNotificationMethod.Event]: parseHcEvent,
+    [HcNotificationMethod.Heartbeat]: parseHcHeartbeat,
+    [HcNotificationMethod.Missed]: parseHcMissed,
+};
+function isNotificationMethod(method) {
+    return isString(method) && Object.hasOwn(NOTIFICATIONS, method);
+}
+export function parseHcNotification(method, params) {
+    return isNotificationMethod(method) ? NOTIFICATIONS[method](params) : err(NOT_A_ROW);
+}
+export function parseHcCoreMessage(input) {
+    if (!isFields(input)) {
+        return err(NOT_A_ROW);
+    }
+    return Object.hasOwn(input, HcField.Method) ? parseHcNotification(input[HcField.Method], input[HcField.Params]) : parseHcReply(input);
+}

package/dist/core-test-kit.d.ts

@@ -0,0 +1,5 @@
+export { FakeFault, FakeHcCore, agentTerminal, frame, later, nextWithin, shellTerminal } from './core/test-kit/fake-core.js';
+export { DemoTerminal, FakeFaultKind, FakeRpcCode, FrameName } from './core/test-kit/constants.js';
+export type { Handler, Seen } from './core/test-kit/fake-core.js';
+export { FAST_EVENTS, FAST_LINK, openWorld, setupTest } from './core/test-kit/setup-test.js';
+export type { DesktopWorld as CoreWorld } from './core/test-kit/setup-test.js';

package/dist/core-test-kit.js

@@ -0,0 +1,5 @@
+// Role: the core test-kit entry ("./core/test-kit"): the fake herdr-core and the setup for tests of code built on the core client (imported by tests only).
+// Informs HERDR-ADR-0020 (the herdr-core client); ported from the desktop work in herdr-plugins.
+export { FakeFault, FakeHcCore, agentTerminal, frame, later, nextWithin, shellTerminal } from './core/test-kit/fake-core.js';
+export { DemoTerminal, FakeFaultKind, FakeRpcCode, FrameName } from './core/test-kit/constants.js';
+export { FAST_EVENTS, FAST_LINK, openWorld, setupTest } from './core/test-kit/setup-test.js';

package/dist/core.d.ts

@@ -0,0 +1,15 @@
+export * from './core/backoff.js';
+export * from './core/constants.js';
+export * from './core/events.js';
+export * from './core/link.js';
+export * from './core/wire.js';
+export { duration } from './core/kernel.js';
+export type { Duration, Instant } from './core/kernel.js';
+export { parseCount } from './core/kernel.js';
+export type { Count } from './core/kernel.js';
+export { parseNonEmptyText, parseText } from './core/kernel.js';
+export type { NonEmptyText, Text } from './core/kernel.js';
+export { byKind, isErr, isOk, must } from './core/kernel.js';
+export type { Err, KindMap, KindOf, Ok, Result } from './core/kernel.js';
+export { CoreInvariantError, isUnknown, unknown } from './core/errors.js';
+export type { ParseFailure, Unknowable, Unknown } from './core/errors.js';

package/dist/core.js

@@ -0,0 +1,12 @@
+// Role: the core entry ("./core"): a typed client of the herdr-core socket (herdr generation 1): CoreLink for calls, CoreEvents for the event feed, the wire parsers and the socket path rule.
+// Informs HERDR-ADR-0020 (the herdr-core client); ported from the desktop work in herdr-plugins.
+export * from './core/backoff.js';
+export * from './core/constants.js';
+export * from './core/events.js';
+export * from './core/link.js';
+export * from './core/wire.js';
+export { duration } from './core/kernel.js';
+export { parseCount } from './core/kernel.js';
+export { parseNonEmptyText, parseText } from './core/kernel.js';
+export { byKind, isErr, isOk, must } from './core/kernel.js';
+export { CoreInvariantError, isUnknown, unknown } from './core/errors.js';

package/dist/drift/cli.d.ts

@@ -0,0 +1,22 @@
+import { DriftExitCode } from '../constants.js';
+import { ArgsKind } from './constants.js';
+import type { DriftOutcome } from './types.js';
+import type { RunHerdr } from './schema.js';
+export declare const HELP_TEXT: string;
+export interface RunArgs {
+    readonly kind: typeof ArgsKind.Run;
+    readonly committed: string | null;
+    readonly herdr: string | null;
+    readonly json: boolean;
+}
+export type ParsedArgs = RunArgs | {
+    readonly kind: typeof ArgsKind.Help;
+} | {
+    readonly kind: typeof ArgsKind.Usage;
+    readonly message: string;
+};
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;
+export declare function renderOutcome(outcome: DriftOutcome): string[];
+export declare function renderJson(outcome: DriftOutcome): string;
+export type SpawnHerdr = (binary: string) => RunHerdr;
+export declare function runDriftCli(argv: readonly string[], spawnHerdr: SpawnHerdr): Promise<DriftExitCode>;

package/dist/drift/cli.js

@@ -0,0 +1,146 @@
+// Role: the herdr-drift command: arguments, help, rendering and the run.
+// Informs HERDR-ADR-0009, HERDR-ADR-0008; merged by HERDR-ADR-0021 from help-text.ts, args.ts, render.ts, cli.ts.
+import { DriftExitCode, DriftOutcomeKind } from '../constants.js';
+import { DriftName, ArgFlag, ArgsKind, UsageText, DriftFacet, DEFAULT_HERDR_BIN } from './constants.js';
+import { hasMovement, exitCodeFor, outcomeOf, outcomeOrNotCovered } from './diff.js';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { committedSource, installedSource } from './schema.js';
+export const HELP_TEXT = `${DriftName} [--committed <dir>] [--herdr <bin>] [--json] [--help]
+
+  Answers ONE question: does the schema committed in schema/ still match the
+  schema the installed herdr publishes?
+
+  It compares the protocol number, the herdr version and four facets by name:
+  methods, result tags, event kinds and subscribable types. It also reports
+  changed field shapes and methods without a METHOD_RESULT row. A facet that
+  moved is named with what was added and what was removed.
+
+  --committed <dir>  directory holding herdr-api.schema.json and herdr-version.json
+  --herdr <bin>      the herdr binary to ask (default: herdr on PATH)
+  --json             print the report as JSON
+
+  Exits: ${DriftExitCode.Clean} the copy matches · ${DriftExitCode.Drift} it drifted · ${DriftExitCode.Usage} misuse · ${DriftExitCode.NotCovered} NOT COVERED`;
+export function parseArgs(argv) {
+    const run = { committed: null, herdr: null, json: false };
+    let index = 0;
+    while (index < argv.length) {
+        const flag = argv[index] ?? '';
+        if (flag === ArgFlag.Help) {
+            return { kind: ArgsKind.Help };
+        }
+        if (flag === ArgFlag.Json) {
+            run.json = true;
+            index += 1;
+            continue;
+        }
+        if (flag === ArgFlag.Committed || flag === ArgFlag.Herdr) {
+            const value = argv[index + 1];
+            if (value === undefined) {
+                return usage(UsageText.MissingValue(flag));
+            }
+            if (flag === ArgFlag.Committed) {
+                run.committed = value;
+            }
+            else {
+                run.herdr = value;
+            }
+            index += 2;
+            continue;
+        }
+        return usage(UsageText.Unexpected(flag));
+    }
+    return { kind: ArgsKind.Run, ...run };
+}
+function usage(message) {
+    return { kind: ArgsKind.Usage, message };
+}
+export function renderOutcome(outcome) {
+    switch (outcome.kind) {
+        case DriftOutcomeKind.Usage:
+            return [statusLine(DriftExitCode.Usage, `USAGE: ${outcome.message}`)];
+        case DriftOutcomeKind.NotCovered:
+            return [statusLine(DriftExitCode.NotCovered, `NOT COVERED: ${outcome.reason}`)];
+        case DriftOutcomeKind.Report:
+            return reportLines(outcome.report);
+    }
+}
+export function renderJson(outcome) {
+    return JSON.stringify(outcome.kind === DriftOutcomeKind.Report ? outcome.report : outcome, null, 2);
+}
+function reportLines(report) {
+    const findings = findingsOf(report);
+    if (findings.length === 0) {
+        return [statusLine(DriftExitCode.Clean, `clean (protocol ${report.protocol.installed}, herdr ${report.herdrVersion.installed})`)];
+    }
+    return [...findings, statusLine(DriftExitCode.Drift, `${findings.length} finding(s)`)];
+}
+function findingsOf(report) {
+    const findings = [];
+    if (report.protocol.committed !== report.protocol.installed) {
+        findings.push(`protocol moved ${report.protocol.committed} -> ${report.protocol.installed}`);
+    }
+    if (report.herdrVersion.committed !== report.herdrVersion.installed) {
+        findings.push(`herdr version moved ${report.herdrVersion.committed} -> ${report.herdrVersion.installed}`);
+    }
+    const facets = [
+        [DriftFacet.Methods, report.methods],
+        [DriftFacet.ResultTags, report.resultTags],
+        [DriftFacet.EventKinds, report.eventKinds],
+        [DriftFacet.SubscriptionTypes, report.subscriptionTypes],
+    ];
+    for (const [label, diff] of facets) {
+        if (hasMovement(diff)) {
+            findings.push(facetLine(label, diff));
+        }
+    }
+    if (report.changedShapes.length > 0) {
+        findings.push(`field shapes changed: ${report.changedShapes.join(', ')}`);
+    }
+    if (report.unmappedMethods.length > 0) {
+        findings.push(`methods without a METHOD_RESULT row: ${report.unmappedMethods.join(', ')}`);
+    }
+    return findings;
+}
+function facetLine(label, diff) {
+    const parts = [];
+    if (diff.added.length > 0) {
+        parts.push(`herdr ADDED ${diff.added.length} the copy lacks: ${diff.added.join(', ')}`);
+    }
+    if (diff.removed.length > 0) {
+        parts.push(`herdr REMOVED ${diff.removed.length} the copy still has: ${diff.removed.join(', ')}`);
+    }
+    return `${label}: ${parts.join(' · ')}`;
+}
+function statusLine(code, text) {
+    return `${DriftName}: ${code} — ${text}`;
+}
+// The committed schema directory of the package (src/drift and dist/drift are both two levels below the package root).
+const DEFAULT_SCHEMA_DIR = fileURLToPath(new URL('../../schema', import.meta.url));
+function emit(outcome, json) {
+    const code = exitCodeFor(outcome);
+    const text = json ? renderJson(outcome) : renderOutcome(outcome).join('\n');
+    const stream = code >= DriftExitCode.Usage ? process.stderr : process.stdout;
+    stream.write(`${text}\n`);
+    return code;
+}
+// Reads both schemas and compares them. Any error thrown here is caught by runDriftCli and reported as NOT COVERED.
+async function lookAt(parsed, spawnHerdr) {
+    const readText = (path) => readFileSync(path, 'utf8');
+    const committed = await committedSource(parsed.committed ?? DEFAULT_SCHEMA_DIR, readText)();
+    const installed = await installedSource(spawnHerdr(parsed.herdr ?? DEFAULT_HERDR_BIN))();
+    return outcomeOf(committed, installed);
+}
+// Runs the CLI for the given arguments (without the node or bun and script entries) and returns the exit code the process should use.
+// `spawnHerdr` runs the herdr CLI; bin/herdr-drift.js passes the real one.
+export async function runDriftCli(argv, spawnHerdr) {
+    const parsed = parseArgs(argv);
+    if (parsed.kind === ArgsKind.Help) {
+        process.stdout.write(`${HELP_TEXT}\n`);
+        return DriftExitCode.Clean;
+    }
+    if (parsed.kind === ArgsKind.Usage) {
+        return emit({ kind: DriftOutcomeKind.Usage, message: parsed.message }, false);
+    }
+    return emit(await outcomeOrNotCovered(() => lookAt(parsed, spawnHerdr)), parsed.json);
+}

package/dist/drift/constants.d.ts

@@ -0,0 +1,83 @@
+export declare const DriftName = "herdr-drift";
+export declare const SchemaField: {
+    readonly Protocol: 'protocol';
+    readonly Schemas: 'schemas';
+};
+export declare const SchemaNamespace: {
+    readonly Request: 'request';
+    readonly SuccessResponse: 'success_response';
+    readonly Event: 'event';
+};
+export declare const SchemaDefinition: {
+    readonly ResponseResult: 'ResponseResult';
+    readonly EventData: 'EventData';
+    readonly Subscription: 'Subscription';
+};
+export declare const SchemaKey: {
+    readonly Defs: '$defs';
+    readonly OneOf: 'oneOf';
+    readonly Properties: 'properties';
+    readonly Const: 'const';
+    readonly Description: 'description';
+};
+export declare const TagProperty: {
+    readonly Method: 'method';
+    readonly Type: 'type';
+};
+export declare const DriftFacet: {
+    readonly Methods: 'methods';
+    readonly ResultTags: 'result tags';
+    readonly EventKinds: 'event kinds';
+    readonly SubscriptionTypes: 'subscribable types';
+};
+export declare const JsType: {
+    readonly Object: 'object';
+    readonly String: 'string';
+    readonly Number: 'number';
+};
+export declare const SystemErrorCode: {
+    readonly NotFound: 'ENOENT';
+};
+export declare const SchemaFileName: {
+    readonly Schema: 'herdr-api.schema.json';
+    readonly Version: 'herdr-version.json';
+};
+export declare const VersionFileField: {
+    readonly Version: 'version';
+};
+export declare const HerdrCommand: {
+    readonly Version: readonly ['--version'];
+    readonly SchemaJson: readonly ['api', 'schema', '--json'];
+};
+export declare const HerdrCall: {
+    readonly TimeoutMs: 60000;
+};
+export declare const VERSION_PATTERN: RegExp;
+export declare const DEFAULT_HERDR_BIN = "herdr";
+export declare const ArgFlag: {
+    readonly Committed: '--committed';
+    readonly Herdr: '--herdr';
+    readonly Json: '--json';
+    readonly Help: '--help';
+};
+export declare const ArgsKind: {
+    readonly Run: 'run';
+    readonly Help: 'help';
+    readonly Usage: 'usage';
+};
+export declare const ReasonText: {
+    readonly CommittedMissing: 'the committed schema is not there';
+    readonly CommittedUnreadable: 'the committed schema could not be read';
+    readonly VersionMissing: 'the committed herdr-version.json is not there';
+    readonly VersionFileUnreadable: 'the committed herdr-version.json could not be read';
+    readonly VersionUnreadable: 'the committed herdr-version.json carries no version';
+    readonly NotJson: 'the schema is not JSON';
+    readonly NoProtocol: 'the schema carries no protocol number';
+    readonly HerdrMissing: 'herdr is not on PATH, so the live schema cannot be read';
+    readonly HerdrRefused: 'herdr did not return a schema';
+    readonly HerdrVersionMissing: 'herdr did not report a version';
+};
+export declare const UsageText: {
+    readonly Unexpected: (argument: string) => string;
+    readonly MissingValue: (flag: string) => string;
+};

package/dist/drift/constants.js

@@ -0,0 +1,73 @@
+// Role: lane-local constants of schema drift: schema bundle and definition names, facet labels, reason texts, herdr calls and CLI flags.
+// Informs HERDR-ADR-0009 (drift) and HERDR-ADR-0017 (lane P5c owns src/drift/**). As const objects, so no string literal is compared in code. The exit codes and outcome kinds stay in the root constants.ts.
+export const DriftName = 'herdr-drift';
+export const SchemaField = { Protocol: 'protocol', Schemas: 'schemas' };
+// The three bundles of the published schema that drift reads (schemas.<bundle>).
+export const SchemaNamespace = {
+    Request: 'request',
+    SuccessResponse: 'success_response',
+    Event: 'event',
+};
+// Named definitions drift looks up inside a bundle.
+export const SchemaDefinition = {
+    ResponseResult: 'ResponseResult',
+    EventData: 'EventData',
+    Subscription: 'Subscription',
+};
+// Keywords and property names read inside schema nodes.
+export const SchemaKey = {
+    Defs: '$defs',
+    OneOf: 'oneOf',
+    Properties: 'properties',
+    Const: 'const',
+    Description: 'description',
+};
+// The property that names a branch of a tagged union: a request method or a result, event or subscription type.
+export const TagProperty = { Method: 'method', Type: 'type' };
+// Labels of the facets in the human report (HERDR-ADR-0009).
+export const DriftFacet = {
+    Methods: 'methods',
+    ResultTags: 'result tags',
+    EventKinds: 'event kinds',
+    SubscriptionTypes: 'subscribable types',
+};
+// JavaScript typeof results, so no string literal is compared in code.
+export const JsType = { Object: 'object', String: 'string', Number: 'number' };
+// The one system error code drift reads: a missing executable (`herdr` not on PATH).
+export const SystemErrorCode = { NotFound: 'ENOENT' };
+// Files of the committed schema directory (`schema/`, written by `bun run capture`).
+export const SchemaFileName = { Schema: 'herdr-api.schema.json', Version: 'herdr-version.json' };
+export const VersionFileField = { Version: 'version' };
+// The herdr CLI calls drift makes. They run only in bin/herdr-drift.ts, never against the socket (HERDR-ADR-0008).
+export const HerdrCommand = {
+    Version: ['--version'],
+    SchemaJson: ['api', 'schema', '--json'],
+};
+export const HerdrCall = { TimeoutMs: 60_000 };
+// A semantic version inside the text `herdr --version` prints.
+export const VERSION_PATTERN = /\d+\.\d+\.\d+/;
+export const DEFAULT_HERDR_BIN = 'herdr';
+export const ArgFlag = {
+    Committed: '--committed',
+    Herdr: '--herdr',
+    Json: '--json',
+    Help: '--help',
+};
+export const ArgsKind = { Run: 'run', Help: 'help', Usage: 'usage' };
+// Why a source could not look (exit 3, HERDR-ADR-0009).
+export const ReasonText = {
+    CommittedMissing: 'the committed schema is not there',
+    CommittedUnreadable: 'the committed schema could not be read',
+    VersionMissing: 'the committed herdr-version.json is not there',
+    VersionFileUnreadable: 'the committed herdr-version.json could not be read',
+    VersionUnreadable: 'the committed herdr-version.json carries no version',
+    NotJson: 'the schema is not JSON',
+    NoProtocol: 'the schema carries no protocol number',
+    HerdrMissing: 'herdr is not on PATH, so the live schema cannot be read',
+    HerdrRefused: 'herdr did not return a schema',
+    HerdrVersionMissing: 'herdr did not report a version',
+};
+export const UsageText = {
+    Unexpected: (argument) => `unexpected argument '${argument}'`,
+    MissingValue: (flag) => `${flag} needs a value`,
+};

package/dist/drift/diff.d.ts

@@ -0,0 +1,7 @@
+import type { NameDiff, DriftBetween, DriftOutcome, SchemaRead, ExitCodeFor } from './types.js';
+export declare function nameDiff(committed: readonly string[], installed: readonly string[]): NameDiff;
+export declare function hasMovement(diff: NameDiff): boolean;
+export declare const driftBetween: DriftBetween;
+export declare function outcomeOf(committed: SchemaRead, installed: SchemaRead): DriftOutcome;
+export declare function outcomeOrNotCovered(look: () => Promise<DriftOutcome>): Promise<DriftOutcome>;
+export declare const exitCodeFor: ExitCodeFor;

package/dist/drift/diff.js

@@ -0,0 +1,91 @@
+import { inventoryOf, unmappedMethods } from './schema.js';
+import { DriftOutcomeKind, SchemaReadKind, DriftExitCode } from '../constants.js';
+import { MalformedSchemaError } from '../herdr/errors.js';
+export function nameDiff(committed, installed) {
+    return {
+        added: missingFrom(installed, committed),
+        removed: missingFrom(committed, installed),
+    };
+}
+export function hasMovement(diff) {
+    return diff.added.length > 0 || diff.removed.length > 0;
+}
+function missingFrom(names, others) {
+    const known = new Set(others);
+    return names.filter((name) => !known.has(name)).toSorted();
+}
+export const driftBetween = (committed, installed) => {
+    const copy = inventoryOf(committed.schema, committed.herdrVersion);
+    const live = inventoryOf(installed.schema, installed.herdrVersion);
+    const methods = nameDiff(copy.methods, live.methods);
+    const resultTags = nameDiff(copy.resultTags, live.resultTags);
+    const eventKinds = nameDiff(copy.eventKinds, live.eventKinds);
+    const subscriptionTypes = nameDiff(copy.subscriptionTypes, live.subscriptionTypes);
+    const changedShapes = changedShapesOf(copy, live);
+    const unmapped = unmappedMethods(live.methods);
+    const drifted = copy.protocol !== live.protocol
+        || copy.herdrVersion !== live.herdrVersion
+        || [methods, resultTags, eventKinds, subscriptionTypes].some(hasMovement)
+        || changedShapes.length > 0
+        || unmapped.length > 0;
+    return {
+        protocol: { committed: copy.protocol, installed: live.protocol },
+        herdrVersion: { committed: copy.herdrVersion, installed: live.herdrVersion },
+        methods,
+        resultTags,
+        eventKinds,
+        subscriptionTypes,
+        changedShapes,
+        unmappedMethods: unmapped,
+        drifted,
+    };
+};
+// Types present on both sides whose stable field shape differs (added and removed types are reported by the facets).
+function changedShapesOf(copy, live) {
+    return Object.keys(copy.fieldShapes)
+        .filter((name) => Object.hasOwn(live.fieldShapes, name) && copy.fieldShapes[name] !== live.fieldShapes[name])
+        .toSorted();
+}
+export function outcomeOf(committed, installed) {
+    if (committed.kind !== SchemaReadKind.Found) {
+        return notCovered(committed.reason);
+    }
+    if (installed.kind !== SchemaReadKind.Found) {
+        return notCovered(installed.reason);
+    }
+    return reportOf(committed, installed);
+}
+// Runs the look; any error it throws, expected or not, is NOT COVERED with its message.
+export async function outcomeOrNotCovered(look) {
+    try {
+        return await look();
+    }
+    catch (error) {
+        return notCovered(error instanceof Error ? error.message : String(error));
+    }
+}
+function reportOf(committed, installed) {
+    try {
+        return { kind: DriftOutcomeKind.Report, report: driftBetween(committed, installed) };
+    }
+    catch (error) {
+        // A schema without a required definition or tag cannot be compared, so it counts as not looked at.
+        if (error instanceof MalformedSchemaError) {
+            return notCovered(error.message);
+        }
+        throw error;
+    }
+}
+function notCovered(reason) {
+    return { kind: DriftOutcomeKind.NotCovered, reason };
+}
+export const exitCodeFor = (outcome) => {
+    switch (outcome.kind) {
+        case DriftOutcomeKind.Usage:
+            return DriftExitCode.Usage;
+        case DriftOutcomeKind.NotCovered:
+            return DriftExitCode.NotCovered;
+        case DriftOutcomeKind.Report:
+            return outcome.report.drifted ? DriftExitCode.Drift : DriftExitCode.Clean;
+    }
+};