@daihum/error-state

Neutral typed error-state mechanism for DAIHUM and downstream hosts.

This package owns the runtime-free mechanism:

• the frozen carrel.runtime.error.v0 envelope;
• local const error-kind declarations through defineErrorKinds;
• ErrorStateOf<typeof kinds> type derivation;
• a registry contribution port;
• an injected schema validation port for typed details.

It deliberately does not own product feature declarations, registry storage, documentation generation, Carrel migration, or schema-library choice.

import { defineErrorKinds, type SchemaPort } from "@daihum/error-state";

interface MissingDocumentDetails {
  readonly fileUri: string;
}

const missingDocumentDetails: SchemaPort<MissingDocumentDetails> = {
  validate(value) {
    if (
      typeof value === "object" &&
      value !== null &&
      typeof (value as { fileUri?: unknown }).fileUri === "string"
    ) {
      return { ok: true, value: { fileUri: (value as { fileUri: string }).fileUri } };
    }
    return { ok: false, error: { message: "fileUri is required" } };
  },
};

export const readerErrors = defineErrorKinds("reader.pdf", {
  missingDocument: {
    retryable: false,
    reason: "missing-document",
    message: "The PDF document is not available.",
    details: missingDocumentDetails,
  },
} as const);

const state = readerErrors.fail("missingDocument", {
  commandId: "reader.open",
  details: { fileUri: "file:///paper.pdf" },
});

The returned state uses the same frozen wire schema:

state.schema === "carrel.runtime.error.v0";

No runtime dependencies are used.