@omnicross/contracts 0.1.2 → 0.1.4

package/dist/audit-types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Request-audit contracts (request-audit-log, design D1/D2).
+ *
+ * Two dependency-light shapes shared across the `@omnicross/*` packages:
+ *  - `AuditRecord` — the FROZEN per-request audit entry. It carries request
+ *    METADATA (who/where/when/status/latency/model) plus, ONLY when body capture
+ *    is explicitly enabled, a redacted+truncated request/response body snapshot.
+ *    It is SECRET-FREE BY CONSTRUCTION: it holds the outbound key ID (NEVER the
+ *    key material/hash), the client IP + user-agent (PII, hence the whole store
+ *    is authed-only + TTL-pruned), and NEVER a token, Authorization header, or
+ *    api-key header value (request headers are NEVER captured). A secret-scan
+ *    test asserts no key/token pattern survives in a written record.
+ *  - `AuditConfig` — the `audit` config segment. Two independent switches:
+ *    `enabled` (record metadata) and `captureBodies` (the sensitive second
+ *    opt-in — record bodies too), both default OFF (zero regression).
+ *
+ * @module audit-types
+ */
+/**
+ * One per-request audit entry (design D1). The metadata fields are recorded
+ * whenever audit is `enabled`; the two body snapshots are present ONLY when
+ * `captureBodies` is ALSO on, and always after truncation + redaction. NO field
+ * ever holds key material, an upstream token, or an Authorization/api-key header.
+ */
+interface AuditRecord {
+    /** Unique record id (a generated request id — NOT any secret). */
+    id: string;
+    /** Epoch ms the request was captured. */
+    ts: number;
+    /** Outbound key id (attribution) — NEVER the key secret/hash. Null when unauthenticated. */
+    keyId?: string | null;
+    /** Client IP (PII). Socket address by default; a trusted forwarded header only when configured. */
+    ip?: string;
+    /** Client user-agent (PII). */
+    ua?: string;
+    /** HTTP method. */
+    method: string;
+    /** Request path (query string dropped so no secret query param is stored). */
+    path: string;
+    /** Resolved upstream model. */
+    model?: string;
+    /** Upstream provider id (or `'byo'`). */
+    provider?: string;
+    /** HTTP status the client received. */
+    status: number;
+    /** End-to-end latency (ms). */
+    latencyMs: number;
+    /** Prompt-side token count (present only when the host correlates usage). */
+    inputTokens?: number;
+    /** Completion-side token count (present only when the host correlates usage). */
+    outputTokens?: number;
+    /** Cost in USD (present only when the host correlates usage). */
+    costUsd?: number;
+    /** Sanitized error message (present only on a failed relay). */
+    error?: string;
+    /**
+     * Request body snapshot — present ONLY when `captureBodies`, truncated to the
+     * configured cap, and ALWAYS run through the secret-redaction pass first.
+     */
+    requestBody?: string;
+    /**
+     * Response body snapshot — present ONLY when `captureBodies` AND the response
+     * was NON-streaming (a streaming response records metadata only), truncated +
+     * redacted like `requestBody`.
+     */
+    responseBody?: string;
+}
+/**
+ * The `audit` config segment (design D2), normalized like `accountHealth`.
+ * Absent/`enabled:false` ⇒ no sink wired + no capture ⇒ byte-identical zero
+ * regression. `captureBodies` is a SEPARATE, sensitive opt-in that does nothing
+ * unless `enabled` is also on.
+ */
+interface AuditConfig {
+    /** Master switch; default FALSE (zero regression). */
+    enabled: boolean;
+    /** Capture request/response bodies too (redacted+truncated); default FALSE. */
+    captureBodies: boolean;
+    /** Per-body truncation cap in bytes; default 8192, clamped. */
+    maxBodyBytes: number;
+    /** TTL retention in days; default 7, clamped `[1, 365]`. */
+    retentionDays: number;
+    /**
+     * Trust the `X-Forwarded-For` header for the client IP (LEAD OQ1 anti-spoof).
+     * Default FALSE — the socket remote address is authoritative. Only set true
+     * behind a trusted reverse proxy; a client-supplied XFF is NEVER trusted by
+     * default.
+     */
+    trustForwardedFor: boolean;
+}
+/** Frozen defaults for the `audit` segment (SSOT). */
+declare const DEFAULT_AUDIT_CONFIG: AuditConfig;
+/** One page of audit records the authed admin query returns (newest first). */
+interface AuditQueryResult {
+    records: AuditRecord[];
+}
+
+export { type AuditConfig, type AuditQueryResult, type AuditRecord, DEFAULT_AUDIT_CONFIG };

package/dist/audit-types.js

@@ -0,0 +1,11 @@
+// src/audit-types.ts
+var DEFAULT_AUDIT_CONFIG = {
+  enabled: false,
+  captureBodies: false,
+  maxBodyBytes: 8192,
+  retentionDays: 7,
+  trustForwardedFor: false
+};
+export {
+  DEFAULT_AUDIT_CONFIG
+};

package/dist/billing-types.cjs

@@ -0,0 +1,33 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/billing-types.ts
+var billing_types_exports = {};
+__export(billing_types_exports, {
+  DEFAULT_BILLING_CONFIG: () => DEFAULT_BILLING_CONFIG
+});
+module.exports = __toCommonJS(billing_types_exports);
+var DEFAULT_BILLING_CONFIG = {
+  enabled: false,
+  maxRetryAgeMs: 24 * 60 * 6e4
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_BILLING_CONFIG
+});

package/dist/billing-types.d.cts

@@ -0,0 +1,98 @@
+/**
+ * Billing-event-stream contracts (billing-event-stream, design D1/D6).
+ *
+ * Two dependency-light shapes shared across the `@omnicross/*` packages:
+ *  - `BillingEvent` — the FROZEN per-request metered fact an EXTERNAL consumer
+ *    ingests (a metering service, a data warehouse, a billing platform). It is
+ *    SECRET-FREE BY CONSTRUCTION: it carries the outbound key ID (an id, NEVER
+ *    the key material/hash) and NEVER a token, Authorization header, or the
+ *    signing secret. Its `id` (the request id) doubles as the consumer's
+ *    IDEMPOTENCY KEY — delivery is at-least-once, so a consumer dedupes by `id`.
+ *    A secret-scan test asserts no key/token/secret pattern survives in a
+ *    written/POSTed event.
+ *  - `BillingConfig` — the `billing` config segment. Default OFF (zero
+ *    regression). Carries the OPTIONAL POST `endpoint` (absent ⇒ ledger-only
+ *    mode) and the OPTIONAL HMAC `secret` (the ONLY secret — encrypted at rest +
+ *    masked in admin, never in a payload/log).
+ *
+ * Distinct from `usage-events.jsonl` (internal dashboard telemetry): billing is
+ * the external-facing metered fact with its OWN schema + delivery + HMAC.
+ *
+ * @module billing-types
+ */
+/**
+ * One per-request billing event (design D1) — the metered fact for external
+ * consumption. Produced at the post-response point from the SAME computed cost
+ * the usage telemetry records (no double pricing). NO field ever holds key
+ * material, an upstream token, or the HMAC signing secret.
+ */
+interface BillingEvent {
+    /**
+     * Request id — the consumer's IDEMPOTENCY KEY. Stable for one event across
+     * delivery RETRIES (the retry sweep re-POSTs the SAME id) so an at-least-once
+     * consumer applies it exactly once. NOT any secret.
+     */
+    id: string;
+    /** Epoch ms the request was billed (the request timestamp). */
+    ts: number;
+    /** Outbound key id (attribution) — NEVER the key secret/hash. Null when unattributed. */
+    keyId?: string | null;
+    /** Resolved upstream model the request billed against. */
+    model: string;
+    /** Upstream provider id (or `'byo'`). */
+    provider?: string;
+    /** Re-auth mode the request billed under (BYO key vs subscription OAuth). */
+    authMode: 'byo' | 'subscription';
+    /** Prompt-side token count. */
+    inputTokens: number;
+    /** Completion-side token count. */
+    outputTokens: number;
+    /** Cost in USD (the SAME value the usage telemetry recorded). */
+    costUsd: number;
+    /** HTTP status of the billed request. */
+    status: number;
+}
+/**
+ * The `billing` config segment (design D6), normalized like `audit`.
+ * Absent/`enabled:false` ⇒ no sink wired ⇒ `publishBillingEvent` is a no-op ⇒
+ * no append, no POST, byte-identical zero regression. `enabled` WITHOUT an
+ * `endpoint` is a first-class LEDGER-ONLY mode (the durable jsonl IS the product;
+ * an external tailer consumes it). The `secret` is the ONLY secret field
+ * (encrypted at rest + masked in admin).
+ */
+interface BillingConfig {
+    /** Master switch; default FALSE (zero regression). */
+    enabled: boolean;
+    /**
+     * POST target for the built-in delivery. ABSENT ⇒ ledger-only mode: events are
+     * durably appended and an external consumer tails the jsonl directly (no push).
+     */
+    endpoint?: string;
+    /**
+     * HMAC-SHA256 signing key — a SECRET. When set, each POST carries
+     * `X-Omnicross-Billing-Signature: sha256=<hmac hex of body>`. Encrypted at rest
+     * + masked in admin views; the secret ONLY signs, it NEVER travels in the event
+     * payload or a log line.
+     */
+    secret?: string;
+    /**
+     * Stop RE-POSTing an undelivered event after this age (ms); default 24h,
+     * clamped. This governs RETRY only — an over-age undelivered event is RETAINED
+     * in the ledger for reconciliation, NEVER deleted (a billing ledger is a
+     * financial record).
+     */
+    maxRetryAgeMs: number;
+}
+/** Frozen defaults for the `billing` segment (SSOT). 24h retry bound. */
+declare const DEFAULT_BILLING_CONFIG: BillingConfig;
+/** Aggregate delivery status the authed admin surfaces (secret-free counts). */
+interface BillingDeliveryStatus {
+    /** Total events in the durable ledger. */
+    total: number;
+    /** Events an external endpoint has acknowledged (delivered). */
+    delivered: number;
+    /** Events not yet delivered (still retried within `maxRetryAgeMs`, then retained). */
+    pending: number;
+}
+
+export { type BillingConfig, type BillingDeliveryStatus, type BillingEvent, DEFAULT_BILLING_CONFIG };

package/dist/billing-types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Billing-event-stream contracts (billing-event-stream, design D1/D6).
+ *
+ * Two dependency-light shapes shared across the `@omnicross/*` packages:
+ *  - `BillingEvent` — the FROZEN per-request metered fact an EXTERNAL consumer
+ *    ingests (a metering service, a data warehouse, a billing platform). It is
+ *    SECRET-FREE BY CONSTRUCTION: it carries the outbound key ID (an id, NEVER
+ *    the key material/hash) and NEVER a token, Authorization header, or the
+ *    signing secret. Its `id` (the request id) doubles as the consumer's
+ *    IDEMPOTENCY KEY — delivery is at-least-once, so a consumer dedupes by `id`.
+ *    A secret-scan test asserts no key/token/secret pattern survives in a
+ *    written/POSTed event.
+ *  - `BillingConfig` — the `billing` config segment. Default OFF (zero
+ *    regression). Carries the OPTIONAL POST `endpoint` (absent ⇒ ledger-only
+ *    mode) and the OPTIONAL HMAC `secret` (the ONLY secret — encrypted at rest +
+ *    masked in admin, never in a payload/log).
+ *
+ * Distinct from `usage-events.jsonl` (internal dashboard telemetry): billing is
+ * the external-facing metered fact with its OWN schema + delivery + HMAC.
+ *
+ * @module billing-types
+ */
+/**
+ * One per-request billing event (design D1) — the metered fact for external
+ * consumption. Produced at the post-response point from the SAME computed cost
+ * the usage telemetry records (no double pricing). NO field ever holds key
+ * material, an upstream token, or the HMAC signing secret.
+ */
+interface BillingEvent {
+    /**
+     * Request id — the consumer's IDEMPOTENCY KEY. Stable for one event across
+     * delivery RETRIES (the retry sweep re-POSTs the SAME id) so an at-least-once
+     * consumer applies it exactly once. NOT any secret.
+     */
+    id: string;
+    /** Epoch ms the request was billed (the request timestamp). */
+    ts: number;
+    /** Outbound key id (attribution) — NEVER the key secret/hash. Null when unattributed. */
+    keyId?: string | null;
+    /** Resolved upstream model the request billed against. */
+    model: string;
+    /** Upstream provider id (or `'byo'`). */
+    provider?: string;
+    /** Re-auth mode the request billed under (BYO key vs subscription OAuth). */
+    authMode: 'byo' | 'subscription';
+    /** Prompt-side token count. */
+    inputTokens: number;
+    /** Completion-side token count. */
+    outputTokens: number;
+    /** Cost in USD (the SAME value the usage telemetry recorded). */
+    costUsd: number;
+    /** HTTP status of the billed request. */
+    status: number;
+}
+/**
+ * The `billing` config segment (design D6), normalized like `audit`.
+ * Absent/`enabled:false` ⇒ no sink wired ⇒ `publishBillingEvent` is a no-op ⇒
+ * no append, no POST, byte-identical zero regression. `enabled` WITHOUT an
+ * `endpoint` is a first-class LEDGER-ONLY mode (the durable jsonl IS the product;
+ * an external tailer consumes it). The `secret` is the ONLY secret field
+ * (encrypted at rest + masked in admin).
+ */
+interface BillingConfig {
+    /** Master switch; default FALSE (zero regression). */
+    enabled: boolean;
+    /**
+     * POST target for the built-in delivery. ABSENT ⇒ ledger-only mode: events are
+     * durably appended and an external consumer tails the jsonl directly (no push).
+     */
+    endpoint?: string;
+    /**
+     * HMAC-SHA256 signing key — a SECRET. When set, each POST carries
+     * `X-Omnicross-Billing-Signature: sha256=<hmac hex of body>`. Encrypted at rest
+     * + masked in admin views; the secret ONLY signs, it NEVER travels in the event
+     * payload or a log line.
+     */
+    secret?: string;
+    /**
+     * Stop RE-POSTing an undelivered event after this age (ms); default 24h,
+     * clamped. This governs RETRY only — an over-age undelivered event is RETAINED
+     * in the ledger for reconciliation, NEVER deleted (a billing ledger is a
+     * financial record).
+     */
+    maxRetryAgeMs: number;
+}
+/** Frozen defaults for the `billing` segment (SSOT). 24h retry bound. */
+declare const DEFAULT_BILLING_CONFIG: BillingConfig;
+/** Aggregate delivery status the authed admin surfaces (secret-free counts). */
+interface BillingDeliveryStatus {
+    /** Total events in the durable ledger. */
+    total: number;
+    /** Events an external endpoint has acknowledged (delivered). */
+    delivered: number;
+    /** Events not yet delivered (still retried within `maxRetryAgeMs`, then retained). */
+    pending: number;
+}
+
+export { type BillingConfig, type BillingDeliveryStatus, type BillingEvent, DEFAULT_BILLING_CONFIG };

package/dist/billing-types.js

@@ -0,0 +1,8 @@
+// src/billing-types.ts
+var DEFAULT_BILLING_CONFIG = {
+  enabled: false,
+  maxRetryAgeMs: 24 * 60 * 6e4
+};
+export {
+  DEFAULT_BILLING_CONFIG
+};

package/dist/canonical-models.d.cts

@@ -1,5 +1,5 @@
 import { T as ThinkLevel } from './thinking-CBWSLel8.cjs';
-import { M as ModelConfig } from './llm-config-CQjOimv2.cjs';
+import { M as ModelConfig } from './llm-config-DeWNx1ig.cjs';
 
 /**
  * Canonical Model Registry

package/dist/canonical-models.d.ts

@@ -1,5 +1,5 @@
 import { T as ThinkLevel } from './thinking-CBWSLel8.js';
-import { M as ModelConfig } from './llm-config-D1jKQLVp.js';
+import { M as ModelConfig } from './llm-config-CKOaFFdy.js';
 
 /**
  * Canonical Model Registry

package/dist/endpoint-resolver.d.cts

@@ -1,4 +1,4 @@
-import { L as LLMProvider } from './llm-config-CQjOimv2.cjs';
+import { L as LLMProvider } from './llm-config-DeWNx1ig.cjs';
 import './thinking-CBWSLel8.cjs';
 
 /**

package/dist/endpoint-resolver.d.ts

@@ -1,4 +1,4 @@
-import { L as LLMProvider } from './llm-config-D1jKQLVp.js';
+import { L as LLMProvider } from './llm-config-CKOaFFdy.js';
 import './thinking-CBWSLel8.js';
 
 /**

package/dist/health-logging-types.cjs

@@ -0,0 +1,32 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/health-logging-types.ts
+var health_logging_types_exports = {};
+__export(health_logging_types_exports, {
+  healthHttpStatus: () => healthHttpStatus
+});
+module.exports = __toCommonJS(health_logging_types_exports);
+function healthHttpStatus(status) {
+  return status === "ok" ? 200 : 503;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  healthHttpStatus
+});

package/dist/health-logging-types.d.cts

@@ -0,0 +1,68 @@
+/**
+ * Health-probe + logging contracts (daemon-health-endpoint / configurable-logging).
+ *
+ * Two small, dependency-light shapes shared across the `@omnicross/*` packages:
+ *  - `HealthReport` — the coarse, SECRET-FREE body served by the unauthenticated
+ *    `/health` probe (mounted on the admin server before its auth gate, and
+ *    optionally on the outbound `/v1/*` server before key-auth). Frozen so a
+ *    liveness/readiness probe + sibling changes (#8 health-cron surfacing into
+ *    `checks`) agree on one shape.
+ *  - `LogLevel` / `LoggingConfig` — the configurable-logger's level enum + config
+ *    segment. Frozen so sibling changes (#5 webhooks / #13 audit-log) reuse the
+ *    SAME level vocabulary + config shape rather than reinventing it.
+ *
+ * NON-SECRET by construction: nothing here carries a token, email, config value,
+ * or record-of-count. `HealthReport.checks` are COARSE booleans only.
+ *
+ * @module health-logging-types
+ */
+/** The coarse health status. Anything other than `ok` maps to HTTP 503. */
+type HealthStatus = 'ok' | 'degraded' | 'error';
+/**
+ * The `/health` probe body (design D2). COARSE + SECRET-FREE:
+ *  - `status`        — `ok` (200) | `degraded` | `error` (both 503).
+ *  - `version`       — the daemon package version (already exposed pre-auth via
+ *                      the `x-omnicross-daemon` response header; non-sensitive).
+ *  - `uptimeSeconds` — `Math.floor(process.uptime())`.
+ *  - `timestamp`     — ISO time the report was built.
+ *  - `memory`        — coarse process stats (rss / heapUsed, MB).
+ *  - `checks`        — COARSE dependency booleans ONLY (never tokens/emails/
+ *                      config-values/record-counts).
+ */
+interface HealthReport {
+    status: HealthStatus;
+    version: string;
+    uptimeSeconds: number;
+    timestamp: string;
+    memory: {
+        rssMb: number;
+        heapUsedMb: number;
+    };
+    checks: Record<string, boolean>;
+}
+/** Map a {@link HealthStatus} to its probe HTTP code: `ok` → 200, else → 503. */
+declare function healthHttpStatus(status: HealthStatus): number;
+/**
+ * The logger's level threshold (configurable-logging, design D3). Numeric
+ * severity order `error(0) < warn(1) < info(2) < debug(3)`; a message at a level
+ * BELOW the configured threshold's severity (i.e. a higher ordinal) is dropped.
+ */
+type LogLevel = 'error' | 'warn' | 'info' | 'debug';
+/** Output shape of the logger sinks. */
+type LogFormat = 'text' | 'json';
+/**
+ * The daemon's `logging` config segment (design D3/D4). ALL fields optional; an
+ * absent/empty segment reads as the zero-regression default (console + all
+ * levels + text — byte-identical to the legacy `ConsoleLogger`).
+ *  - `level`  — threshold (default `debug` = print everything).
+ *  - `format` — `text` (human-readable, legacy shape) | `json` (structured lines).
+ *  - `file`   — OPTIONAL append-only file sink path. A PLAIN config value (NOT a
+ *               secret — never walked by the at-rest secret encryption).
+ */
+interface LoggingConfig {
+    level?: LogLevel;
+    format?: LogFormat;
+    file?: string;
+}
+
+export { type HealthReport, type HealthStatus, type LogFormat, type LogLevel, type LoggingConfig, healthHttpStatus };

package/dist/health-logging-types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Health-probe + logging contracts (daemon-health-endpoint / configurable-logging).
+ *
+ * Two small, dependency-light shapes shared across the `@omnicross/*` packages:
+ *  - `HealthReport` — the coarse, SECRET-FREE body served by the unauthenticated
+ *    `/health` probe (mounted on the admin server before its auth gate, and
+ *    optionally on the outbound `/v1/*` server before key-auth). Frozen so a
+ *    liveness/readiness probe + sibling changes (#8 health-cron surfacing into
+ *    `checks`) agree on one shape.
+ *  - `LogLevel` / `LoggingConfig` — the configurable-logger's level enum + config
+ *    segment. Frozen so sibling changes (#5 webhooks / #13 audit-log) reuse the
+ *    SAME level vocabulary + config shape rather than reinventing it.
+ *
+ * NON-SECRET by construction: nothing here carries a token, email, config value,
+ * or record-of-count. `HealthReport.checks` are COARSE booleans only.
+ *
+ * @module health-logging-types
+ */
+/** The coarse health status. Anything other than `ok` maps to HTTP 503. */
+type HealthStatus = 'ok' | 'degraded' | 'error';
+/**
+ * The `/health` probe body (design D2). COARSE + SECRET-FREE:
+ *  - `status`        — `ok` (200) | `degraded` | `error` (both 503).
+ *  - `version`       — the daemon package version (already exposed pre-auth via
+ *                      the `x-omnicross-daemon` response header; non-sensitive).
+ *  - `uptimeSeconds` — `Math.floor(process.uptime())`.
+ *  - `timestamp`     — ISO time the report was built.
+ *  - `memory`        — coarse process stats (rss / heapUsed, MB).
+ *  - `checks`        — COARSE dependency booleans ONLY (never tokens/emails/
+ *                      config-values/record-counts).
+ */
+interface HealthReport {
+    status: HealthStatus;
+    version: string;
+    uptimeSeconds: number;
+    timestamp: string;
+    memory: {
+        rssMb: number;
+        heapUsedMb: number;
+    };
+    checks: Record<string, boolean>;
+}
+/** Map a {@link HealthStatus} to its probe HTTP code: `ok` → 200, else → 503. */
+declare function healthHttpStatus(status: HealthStatus): number;
+/**
+ * The logger's level threshold (configurable-logging, design D3). Numeric
+ * severity order `error(0) < warn(1) < info(2) < debug(3)`; a message at a level
+ * BELOW the configured threshold's severity (i.e. a higher ordinal) is dropped.
+ */
+type LogLevel = 'error' | 'warn' | 'info' | 'debug';
+/** Output shape of the logger sinks. */
+type LogFormat = 'text' | 'json';
+/**
+ * The daemon's `logging` config segment (design D3/D4). ALL fields optional; an
+ * absent/empty segment reads as the zero-regression default (console + all
+ * levels + text — byte-identical to the legacy `ConsoleLogger`).
+ *  - `level`  — threshold (default `debug` = print everything).
+ *  - `format` — `text` (human-readable, legacy shape) | `json` (structured lines).
+ *  - `file`   — OPTIONAL append-only file sink path. A PLAIN config value (NOT a
+ *               secret — never walked by the at-rest secret encryption).
+ */
+interface LoggingConfig {
+    level?: LogLevel;
+    format?: LogFormat;
+    file?: string;
+}
+
+export { type HealthReport, type HealthStatus, type LogFormat, type LogLevel, type LoggingConfig, healthHttpStatus };

package/dist/health-logging-types.js

@@ -0,0 +1,7 @@
+// src/health-logging-types.ts
+function healthHttpStatus(status) {
+  return status === "ok" ? 200 : 503;
+}
+export {
+  healthHttpStatus
+};