@sekiban/dcb-core 0.1.0

package/LICENSE

@@ -0,0 +1,86 @@
+Elastic License 2.0
+
+Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+Copyright License
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software.
+
+Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set
+of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+If you or your company make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license for the
+software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+this license.
+
+Termination
+
+If you use the software in violation of this license, such use is not
+licensed, and your licenses will automatically terminate. If the licensor
+provides you with a notice of your violation, and you cease all violation of
+this license no later than 30 days after you receive that notice, your
+licenses will be reinstated retroactively. However, if you violate this
+license after reinstatement, any additional violation will cause your licenses
+to terminate automatically and permanently.
+
+No Liability
+
+As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of the terms or use of the software, under any kind of legal claim.
+
+Definitions
+
+The licensor is the entity offering these terms, and the software is the
+software the licensor makes available under these terms, including any part
+of it.
+
+you refers to the individual or entity agreeing to these terms.
+
+your company is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+
+control means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+your licenses are all the licenses granted to you for the software under
+these terms.
+
+use means anything you do with the software requiring one of your licenses.
+
+trademark means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,13 @@
+# @sekiban/dcb-core
+
+Cloudflare-independent Serialized DCB definitions and domain algebra.
+
+This package contains the portable core types used by the Serialized DCB V1
+domain and client packages. It is published as an ESM package with the public
+surface available from `@sekiban/dcb-core`.
+
+It is not the earlier, unrelated `@sekiban/core` package line.
+
+## License
+
+Elastic License 2.0. See [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Cloudflare-independent building blocks for Serialized DCB V1.
+ *
+ * This package intentionally contains no fetch, storage, queue, or Workers
+ * types.  The runtime and client packages depend on these definitions rather
+ * than the other way around.
+ */
+export type JsonPrimitive = null | boolean | number | string;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export type JsonBoundary = "event-construction" | "state-persistence" | "command-input" | "value";
+export declare class JsonValidationError extends Error {
+    readonly code: "invalid_json_value";
+    readonly boundary: JsonBoundary;
+    readonly path: string;
+    constructor(message: string, boundary?: JsonBoundary, path?: string, options?: ErrorOptions);
+}
+/** Validate and return a JSON value, rejecting non-finite values and cycles. */
+export declare function assertJsonValue(value: unknown, boundary?: JsonBoundary): JsonValue;
+export declare const validateJsonValue: typeof assertJsonValue;
+export declare class DcbDefinitionError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, options?: ErrorOptions);
+}
+/** The event identity carried by the post-G27 internal delivery lanes. */
+export interface CanonicalEventIdentity {
+    readonly eventPayloadName: string;
+    readonly key: string;
+}
+export declare class CanonicalEventIdentityError extends DcbDefinitionError {
+    readonly code: "CANONICAL_EVENT_IDENTITY_INVALID";
+    constructor(message: string);
+}
+/** Build the only accepted durable identity spelling: eventPayloadName. */
+export declare function canonicalEventKey(eventPayloadName: string): string;
+/** Parse the durable eventPayloadName without consulting payload bytes. */
+export declare function parseCanonicalEventKey(key: string): CanonicalEventIdentity;
+export interface TagDefinition {
+    readonly id: string;
+    readonly group: string;
+    readonly content: string;
+    readonly tag: string;
+}
+export type TagInput = TagDefinition | {
+    readonly id?: string;
+    readonly tag?: string;
+    readonly group?: string;
+    readonly content?: string;
+} | string;
+export declare function defineTag(group: string, content: string): TagDefinition;
+export declare function defineTag(input: TagInput): TagDefinition;
+export interface DefinedEvent<TPayload extends JsonValue = JsonValue> {
+    readonly eventName: string;
+    readonly eventPayloadName: string;
+    readonly payload: TPayload;
+}
+export interface EventDefinition<TPayload extends JsonValue = JsonValue> {
+    readonly name: string;
+    readonly eventName: string;
+    readonly eventPayloadName: string;
+    readonly eventType: string;
+    readonly create: (payload: unknown) => DefinedEvent<TPayload>;
+    readonly construct: (payload: unknown) => DefinedEvent<TPayload>;
+    readonly parse: (payload: unknown) => TPayload;
+}
+export type EventParser<TPayload extends JsonValue> = (payload: unknown) => TPayload;
+export type EventDefinitionOptions<TPayload extends JsonValue> = {
+    readonly name?: string;
+    readonly eventName?: string;
+    readonly eventPayloadName?: string;
+    /** Removed by G32: new payload revisions use a new eventPayloadName. */
+    readonly version?: never;
+    readonly parse?: EventParser<TPayload>;
+    readonly parser?: EventParser<TPayload>;
+    readonly validate?: EventParser<TPayload>;
+};
+export declare function defineEvent<TPayload extends JsonValue = JsonValue>(name: string, parser?: EventParser<TPayload>): EventDefinition<TPayload>;
+export declare function defineEvent<TPayload extends JsonValue = JsonValue>(options: EventDefinitionOptions<TPayload>): EventDefinition<TPayload>;
+export type ProjectorState = JsonValue;
+export type ProjectorEvent = DefinedEvent | {
+    readonly eventName?: string;
+    readonly eventPayloadName?: string;
+    readonly eventType?: string;
+    readonly payload?: unknown;
+};
+export type ProjectorHandler<TState extends JsonValue = JsonValue> = (state: TState, event: DefinedEvent) => TState;
+export interface ProjectorDefinition<TState extends JsonValue = JsonValue> {
+    readonly id: string;
+    readonly projectorId: string;
+    readonly version: number;
+    readonly projectorVersion: number;
+    readonly subscribedEventNames: readonly string[];
+    readonly subscribedEventTypes: readonly string[];
+    readonly initialState: TState;
+    readonly apply: (state: TState, event: ProjectorEvent) => TState;
+    readonly reduce: (state: TState, event: ProjectorEvent) => TState;
+    readonly serializeState: (state: TState) => string;
+    readonly deserializeState: (serialized: string) => TState;
+}
+export type ProjectorDefinitionOptions<TState extends JsonValue = JsonValue> = {
+    readonly id?: string;
+    readonly projectorId?: string;
+    readonly version?: number;
+    readonly projectorVersion?: number;
+    readonly subscribedEventNames?: readonly string[];
+    readonly subscriptions?: readonly string[];
+    readonly events?: readonly (string | EventDefinition)[];
+    readonly subscribedEventTypes?: readonly string[];
+    readonly initialState: TState;
+    readonly handlers?: Readonly<Record<string, ProjectorHandler<TState>>>;
+    readonly eventHandlers?: Readonly<Record<string, ProjectorHandler<TState>>>;
+    /** Optional canonical-key handlers; name handlers remain valid for v1. */
+    readonly eventTypeHandlers?: Readonly<Record<string, ProjectorHandler<TState>>>;
+    readonly serializeState?: (state: TState) => string;
+    readonly deserializeState?: (serialized: string) => TState;
+};
+export declare function defineProjector<TState extends JsonValue = JsonValue>(options: ProjectorDefinitionOptions<TState>): ProjectorDefinition<TState>;
+export interface AppendedEvent {
+    readonly event: EventDefinition;
+    readonly payload: JsonValue;
+    readonly tags: readonly TagDefinition[];
+}
+export interface CommandContext<TState extends JsonValue = JsonValue> {
+    readonly state: <T extends JsonValue = JsonValue>(tag: TagInput) => T | undefined;
+    readonly assertEmpty: (tag: TagInput) => void;
+    readonly append: (event: EventDefinition, payload: unknown, tags?: readonly TagInput[]) => AppendedEvent;
+    readonly done: (value?: JsonValue) => CommandDone<TState>;
+    readonly noop: (reason?: string) => Omit<CommandNoop, "events">;
+    readonly reject: (reason: string, code?: string) => Omit<CommandRejected, "events">;
+    readonly appendedEvents: readonly AppendedEvent[];
+}
+export interface CommandCommitted<TState extends JsonValue = JsonValue> {
+    readonly kind: "committed";
+    readonly value?: JsonValue;
+    readonly state?: TState;
+    readonly events: readonly AppendedEvent[];
+}
+export interface CommandDone<TState extends JsonValue = JsonValue> {
+    readonly kind: "committed";
+    readonly value?: JsonValue;
+    readonly state?: TState;
+}
+export interface CommandNoop {
+    readonly kind: "noop";
+    readonly reason?: string;
+    readonly events: readonly [];
+}
+export interface CommandRejected {
+    readonly kind: "rejected";
+    readonly reason: string;
+    readonly code: string;
+    readonly events: readonly [];
+}
+export type CommandHandlerOutcome<TState extends JsonValue = JsonValue> = CommandDone<TState> | Omit<CommandNoop, "events"> | Omit<CommandRejected, "events">;
+export type CommandOutcome<TState extends JsonValue = JsonValue> = CommandCommitted<TState> | CommandNoop | CommandRejected;
+export declare const done: <TState extends JsonValue = JsonValue>(value?: JsonValue, state?: TState) => CommandDone<TState>;
+export declare const noop: (reason?: string) => CommandNoop;
+export declare const reject: (reason: string, code?: string) => CommandRejected;
+export type CommandInputParser<TInput> = (input: unknown) => TInput;
+export type CommandHandler<TInput, TState extends JsonValue = JsonValue> = (input: TInput, context: CommandContext<TState>) => CommandHandlerOutcome<TState>;
+export interface CommandDefinition<TInput = unknown, TState extends JsonValue = JsonValue> {
+    readonly id: string;
+    readonly name: string;
+    readonly parseInput: (input: unknown) => TInput;
+    readonly execute: (input: unknown, options?: {
+        readonly state?: Readonly<Record<string, JsonValue>>;
+    }) => CommandOutcome<TState>;
+    readonly handle: CommandDefinition<TInput, TState>["execute"];
+}
+export type CommandDefinitionOptions<TInput, TState extends JsonValue = JsonValue> = {
+    readonly id?: string;
+    readonly name?: string;
+    readonly parseInput?: CommandInputParser<TInput>;
+    readonly inputParser?: CommandInputParser<TInput>;
+    readonly input?: CommandInputParser<TInput>;
+    readonly handler: CommandHandler<TInput, TState>;
+};
+export declare function defineCommand<TInput, TState extends JsonValue = JsonValue>(options: CommandDefinitionOptions<TInput, TState>): CommandDefinition<TInput, TState>;
+export interface DomainComponentDefinition {
+    readonly id?: string;
+    readonly name?: string;
+    readonly version?: number;
+    readonly projectorVersion?: number;
+    readonly queryVersion?: number;
+}
+export interface DomainCollision {
+    readonly kind: "event-name" | "command-id" | "projector-id" | "query-id" | "materialized-view-id" | "version-pair";
+    readonly id: string;
+    readonly version?: number;
+    readonly indexes: readonly number[];
+}
+export declare class DomainDefinitionError extends DcbDefinitionError {
+    readonly code: "DOMAIN_DEFINITION_INVALID";
+    readonly collisions: readonly DomainCollision[];
+    constructor(collisions: readonly DomainCollision[]);
+}
+export interface DomainDefinition {
+    readonly events: readonly EventDefinition[];
+    readonly commands: readonly CommandDefinition[];
+    readonly projectors: readonly DomainProjectorDefinition[];
+    readonly queries: readonly DomainComponentDefinition[];
+    readonly materializedViews: readonly DomainComponentDefinition[];
+    readonly eventByName: ReadonlyMap<string, EventDefinition>;
+}
+/** The identity portion needed when registering a projector in a domain. */
+export interface DomainProjectorDefinition {
+    readonly id: string;
+    readonly version: number;
+}
+export type DomainDefinitionOptions = {
+    readonly events?: readonly EventDefinition[];
+    readonly commands?: readonly CommandDefinition[];
+    readonly projectors?: readonly DomainProjectorDefinition[];
+    readonly queries?: readonly DomainComponentDefinition[];
+    readonly materializedViews?: readonly DomainComponentDefinition[];
+    readonly mvs?: readonly DomainComponentDefinition[];
+};
+export declare function defineDomain(options: DomainDefinitionOptions): DomainDefinition;
+export * from "./materializedView.js";

package/dist/index.js

@@ -0,0 +1,490 @@
+// src/materializedView.ts
+function nonEmpty(value, code, message) {
+  if (typeof value !== "string" || value.length === 0) throw new Error(`${code}: ${message}`);
+}
+function descriptorValue(descriptor, value) {
+  if (descriptor.valueType === "text") {
+    if (typeof value !== "string") throw new Error(`MV index ${descriptor.id} expected a text value`);
+    return value;
+  }
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`MV index ${descriptor.id} expected a finite numeric value`);
+  }
+  if (descriptor.valueType === "integer" && (!Number.isSafeInteger(value) || !Number.isInteger(value))) {
+    throw new Error(`MV index ${descriptor.id} expected a safe integer value`);
+  }
+  return value;
+}
+function validateDescriptors(descriptors) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const descriptor of descriptors) {
+    nonEmpty(descriptor.id, "MV_INDEX_ID_REQUIRED", "Index descriptor id is required");
+    if (seen.has(descriptor.id)) throw new Error(`MV_INDEX_DUPLICATE: ${descriptor.id}`);
+    seen.add(descriptor.id);
+    if (!["text", "integer", "real"].includes(descriptor.valueType)) {
+      throw new Error(`MV_INDEX_VALUE_TYPE_INVALID: ${descriptor.id}`);
+    }
+    if (typeof descriptor.value !== "function") throw new Error(`MV_INDEX_VALUE_REQUIRED: ${descriptor.id}`);
+  }
+  return Object.freeze(descriptors.map((descriptor) => Object.freeze({ ...descriptor })));
+}
+function normalizeRowInput(input, event) {
+  nonEmpty(input.rowKey, "MV_ROW_KEY_REQUIRED", "Row key is required");
+  const value = assertJsonValue(input.value, "state-persistence");
+  const rowVersion = input.rowVersion ?? 1;
+  if (!Number.isSafeInteger(rowVersion) || rowVersion < 0) throw new Error(`MV_ROW_VERSION_INVALID: ${input.rowKey}`);
+  const sourceSuid = input.sourceSuid ?? (typeof event === "object" && event !== null && "suid" in event && typeof event.suid === "string" ? event.suid : "");
+  nonEmpty(sourceSuid, "MV_SOURCE_SUID_REQUIRED", `Source SUID is required for ${input.rowKey}`);
+  return Object.freeze({ rowKey: input.rowKey, value, rowVersion, sourceSuid });
+}
+function normalizeRowDeletes(values = []) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const value of values) {
+    const rowKey = typeof value === "string" ? value : value.rowKey;
+    nonEmpty(rowKey, "MV_ROW_KEY_REQUIRED", "Row delete key is required");
+    keys.add(rowKey);
+  }
+  return Object.freeze([...keys].map((rowKey) => Object.freeze({ rowKey })));
+}
+function normalizeIndexEntries(values, descriptors, rowKey) {
+  const descriptorById = new Map(descriptors.map((descriptor) => [descriptor.id, descriptor]));
+  return Object.freeze(values.map((entry) => {
+    nonEmpty(entry.indexId, "MV_INDEX_ID_REQUIRED", "Index entry id is required");
+    const descriptor = descriptorById.get(entry.indexId);
+    if (descriptor === void 0) throw new Error(`MV_INDEX_UNDECLARED: ${entry.indexId}`);
+    nonEmpty(entry.rowKey, "MV_ROW_KEY_REQUIRED", "Index entry row key is required");
+    if (rowKey !== void 0 && entry.rowKey !== rowKey) {
+      throw new Error(`MV_INDEX_ROW_KEY_MISMATCH: ${entry.indexId}`);
+    }
+    const valueType = entry.valueType ?? descriptor.valueType;
+    if (valueType !== descriptor.valueType) throw new Error(`MV_INDEX_VALUE_TYPE_MISMATCH: ${entry.indexId}`);
+    return Object.freeze({
+      indexId: entry.indexId,
+      valueType,
+      value: descriptorValue(descriptor, entry.value),
+      rowKey: entry.rowKey
+    });
+  }));
+}
+function normalizeRowPatches(values, descriptors, event) {
+  return Object.freeze(values.map((input) => {
+    nonEmpty(input.rowKey, "MV_ROW_KEY_REQUIRED", "Row patch key is required");
+    if (input.kind !== "json_patch") throw new Error(`MV_PATCH_KIND_INVALID: ${input.rowKey}`);
+    const patch = assertJsonValue(input.patch, "state-persistence");
+    if (typeof patch !== "object" || patch === null || Array.isArray(patch)) {
+      throw new Error(`MV_PATCH_OBJECT_REQUIRED: ${input.rowKey}`);
+    }
+    const rowVersion = input.rowVersion ?? 1;
+    if (!Number.isSafeInteger(rowVersion) || rowVersion < 0) throw new Error(`MV_ROW_VERSION_INVALID: ${input.rowKey}`);
+    const sourceSuid = input.sourceSuid ?? (typeof event === "object" && event !== null && "suid" in event && typeof event.suid === "string" ? event.suid : "");
+    nonEmpty(sourceSuid, "MV_SOURCE_SUID_REQUIRED", `Source SUID is required for ${input.rowKey}`);
+    return Object.freeze({
+      kind: "json_patch",
+      rowKey: input.rowKey,
+      patch,
+      rowVersion,
+      sourceSuid,
+      indexEntries: normalizeIndexEntries(input.indexEntries ?? [], descriptors, input.rowKey)
+    });
+  }));
+}
+function normalizePlan(result, descriptors, event) {
+  const value = result;
+  const rawUpserts = value.rowUpserts ?? value.upserts ?? [];
+  const rawDeletes = value.rowDeletes ?? value.deletes ?? [];
+  const rawPatches = value.rowPatches ?? value.patches ?? [];
+  const rowUpserts = rawUpserts.map((row) => normalizeRowInput(row, event));
+  const rowDeletes = normalizeRowDeletes(rawDeletes);
+  const rowPatches = normalizeRowPatches(rawPatches, descriptors, event);
+  const descriptorById = new Map(descriptors.map((descriptor) => [descriptor.id, descriptor]));
+  const explicitEntries = value.indexEntries ?? [];
+  const generatedEntries = [];
+  for (const row of rowUpserts) {
+    for (const descriptor of descriptors) {
+      let candidate;
+      try {
+        candidate = descriptor.value(row.value, event);
+      } catch (error) {
+        throw new Error(`MV_INDEX_VALUE_FAILED: ${descriptor.id}: ${String(error)}`);
+      }
+      if (candidate === void 0 || candidate === null) continue;
+      generatedEntries.push(Object.freeze({
+        indexId: descriptor.id,
+        valueType: descriptor.valueType,
+        value: descriptorValue(descriptor, candidate),
+        rowKey: row.rowKey
+      }));
+    }
+  }
+  generatedEntries.push(...normalizeIndexEntries(explicitEntries, descriptors));
+  const indexDeletes = Object.freeze((value.indexDeletes ?? []).map((entry) => {
+    nonEmpty(entry.rowKey, "MV_ROW_KEY_REQUIRED", "Index delete row key is required");
+    if (entry.indexId !== void 0) {
+      nonEmpty(entry.indexId, "MV_INDEX_ID_REQUIRED", "Index delete id is required");
+      if (!descriptorById.has(entry.indexId)) throw new Error(`MV_INDEX_UNDECLARED: ${entry.indexId}`);
+    }
+    return Object.freeze({ indexId: entry.indexId, rowKey: entry.rowKey });
+  }));
+  return Object.freeze({
+    rowUpserts: Object.freeze(rowUpserts),
+    rowDeletes,
+    rowPatches,
+    indexEntries: Object.freeze(generatedEntries),
+    indexDeletes
+  });
+}
+function defineRowMaterializer(options) {
+  nonEmpty(options.id, "MV_ID_REQUIRED", "Materialized-view id is required");
+  const version = options.version ?? 1;
+  if (!Number.isSafeInteger(version) || version < 1) throw new Error("MV_VERSION_INVALID: version must be positive");
+  const descriptors = validateDescriptors(options.indexDescriptors ?? options.indexes ?? []);
+  const materialize = options.materialize ?? options.plan;
+  if (typeof materialize !== "function") throw new Error(`MV_MATERIALIZER_REQUIRED: ${options.id}`);
+  const plan = (event) => normalizePlan(materialize(event), descriptors, event);
+  return Object.freeze({
+    id: options.id,
+    version,
+    indexDescriptors: descriptors,
+    plan,
+    planFor: plan,
+    mutationPlan: plan
+  });
+}
+var defineMaterializedView = defineRowMaterializer;
+var defineMaterializedViewRowMaterializer = defineRowMaterializer;
+
+// src/index.ts
+var JsonValidationError = class extends Error {
+  code = "invalid_json_value";
+  boundary;
+  path;
+  constructor(message, boundary = "value", path = "$", options) {
+    super(message, options);
+    this.name = "JsonValidationError";
+    this.boundary = boundary;
+    this.path = path;
+  }
+};
+var isPlainRecord = (value) => {
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+};
+function assertJsonValue(value, boundary = "value") {
+  const active = /* @__PURE__ */ new WeakSet();
+  const visit = (candidate, path) => {
+    if (candidate === null || typeof candidate === "string" || typeof candidate === "boolean") {
+      return candidate;
+    }
+    if (typeof candidate === "number") {
+      if (Number.isFinite(candidate)) return candidate;
+      throw new JsonValidationError("JSON numbers must be finite", boundary, path);
+    }
+    if (typeof candidate !== "object") {
+      throw new JsonValidationError(`Value at ${path} is not JSON serializable`, boundary, path);
+    }
+    if (active.has(candidate)) {
+      throw new JsonValidationError(`Cyclic JSON value at ${path}`, boundary, path);
+    }
+    active.add(candidate);
+    try {
+      if (Array.isArray(candidate)) {
+        return candidate.map((item, index) => visit(item, `${path}[${index}]`));
+      }
+      if (!isPlainRecord(candidate)) {
+        throw new JsonValidationError(`Value at ${path} must be a plain JSON object`, boundary, path);
+      }
+      const result = {};
+      for (const [key, item] of Object.entries(candidate)) {
+        result[key] = visit(item, `${path}.${key}`);
+      }
+      return result;
+    } finally {
+      active.delete(candidate);
+    }
+  };
+  return visit(value, "$");
+}
+var validateJsonValue = assertJsonValue;
+var DcbDefinitionError = class extends Error {
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = "DcbDefinitionError";
+    this.code = code;
+  }
+};
+var CanonicalEventIdentityError = class extends DcbDefinitionError {
+  code = "CANONICAL_EVENT_IDENTITY_INVALID";
+  constructor(message) {
+    super("CANONICAL_EVENT_IDENTITY_INVALID", message);
+    this.name = "CanonicalEventIdentityError";
+  }
+};
+function canonicalEventKey(eventPayloadName) {
+  if (typeof eventPayloadName !== "string" || eventPayloadName.length === 0 || eventPayloadName.includes(":")) {
+    throw new CanonicalEventIdentityError("Event payload names must be non-empty and must not contain ':'");
+  }
+  return eventPayloadName;
+}
+function parseCanonicalEventKey(key) {
+  const canonical = canonicalEventKey(key);
+  if (canonical !== key) {
+    throw new CanonicalEventIdentityError("Event identity key is not canonical");
+  }
+  return Object.freeze({ eventPayloadName: key, key });
+}
+var tagParts = (input, content) => {
+  if (typeof input === "string") {
+    if (content !== void 0) return { group: input, content };
+    const separator = input.indexOf(":");
+    if (separator > 0) return { group: input.slice(0, separator), content: input.slice(separator + 1), id: input };
+    throw new DcbDefinitionError("TAG_INVALID", "A tag string must be group:content");
+  }
+  const group = input.group;
+  const tagContent = input.content;
+  const id = input.id ?? input.tag;
+  if (typeof group === "string" && typeof tagContent === "string") return { group, content: tagContent, id };
+  if (typeof id === "string") {
+    const separator = id.indexOf(":");
+    if (separator > 0) return { group: id.slice(0, separator), content: id.slice(separator + 1), id };
+  }
+  throw new DcbDefinitionError("TAG_INVALID", "A tag requires group and content");
+};
+function defineTag(input, content) {
+  const parts = tagParts(input, content);
+  const id = parts.id ?? `${parts.group}:${parts.content}`;
+  if (parts.group.length === 0 || parts.content.length === 0 || id.length === 0) {
+    throw new DcbDefinitionError("TAG_INVALID", "Tag group, content, and id must be non-empty");
+  }
+  return Object.freeze({ id, group: parts.group, content: parts.content, tag: id });
+}
+function defineEvent(input, parser) {
+  const options = typeof input === "string" ? { name: input, parse: parser } : input;
+  const name = options.name ?? options.eventName;
+  if (!name) throw new DcbDefinitionError("EVENT_NAME_REQUIRED", "Event name is required");
+  const eventPayloadName = options.eventPayloadName ?? name;
+  if (Object.prototype.hasOwnProperty.call(options, "version")) {
+    throw new DcbDefinitionError("EVENT_VERSION_REMOVED", "Event version is removed; use a distinct event payload name");
+  }
+  const eventType = canonicalEventKey(eventPayloadName);
+  const validate = options.parse ?? options.parser ?? options.validate ?? ((payload) => payload);
+  const parse = (payload) => {
+    let parsed;
+    try {
+      parsed = validate(payload);
+    } catch (error) {
+      throw new DcbDefinitionError("EVENT_PAYLOAD_INVALID", `Event ${name} payload was rejected`, {
+        cause: error
+      });
+    }
+    return assertJsonValue(parsed, "event-construction");
+  };
+  const create = (payload) => Object.freeze({ eventName: name, eventPayloadName, payload: parse(payload) });
+  return Object.freeze({ name, eventName: name, eventPayloadName, eventType, create, construct: create, parse });
+}
+var eventNameOf = (event) => event.eventName ?? event.eventPayloadName;
+function defineProjector(options) {
+  const id = options.id ?? options.projectorId;
+  if (!id) throw new DcbDefinitionError("PROJECTOR_ID_REQUIRED", "Projector id is required");
+  const handlers = options.handlers ?? options.eventHandlers ?? {};
+  const subscribed = options.subscribedEventNames ?? options.subscriptions ?? options.events?.map((event) => typeof event === "string" ? event : event.name) ?? Object.keys(handlers);
+  const uniqueSubscribed = [...new Set(subscribed)];
+  const eventTypeHandlers = options.eventTypeHandlers ?? {};
+  const subscribedEventTypes = options.subscribedEventTypes ?? options.events?.map(
+    (event) => typeof event === "string" ? canonicalEventKey(event) : event.eventType
+  ) ?? uniqueSubscribed.map((name) => canonicalEventKey(name));
+  const uniqueSubscribedEventTypes = [...new Set(subscribedEventTypes.map((eventType) => parseCanonicalEventKey(eventType).key))];
+  const missing = uniqueSubscribed.filter(
+    (name) => handlers[name] === void 0 && !uniqueSubscribedEventTypes.some(
+      (eventType) => parseCanonicalEventKey(eventType).eventPayloadName === name && eventTypeHandlers[eventType] !== void 0
+    )
+  );
+  if (missing.length > 0) {
+    throw new DcbDefinitionError("PROJECTOR_HANDLER_REQUIRED", `Projector ${id} is missing handlers: ${missing.join(", ")}`);
+  }
+  const version = options.version ?? options.projectorVersion ?? 1;
+  if (!Number.isInteger(version) || version < 1) {
+    throw new DcbDefinitionError("PROJECTOR_VERSION_INVALID", "Projector version must be a positive integer");
+  }
+  const initialState = assertJsonValue(options.initialState, "state-persistence");
+  const apply = (state, event) => {
+    const eventType = "eventType" in event ? event.eventType : void 0;
+    const identity = eventType === void 0 ? void 0 : parseCanonicalEventKey(eventType);
+    const name = identity?.eventPayloadName ?? eventNameOf(event);
+    if (!name || !uniqueSubscribed.includes(name)) return state;
+    if (identity !== void 0 && !uniqueSubscribedEventTypes.includes(identity.key)) {
+      throw new DcbDefinitionError("EVENT_TYPE_UNREGISTERED", `Projector ${id} does not subscribe to ${identity.key}`);
+    }
+    const payload = assertJsonValue(event.payload, "event-construction");
+    const definedEvent = Object.freeze({
+      eventName: name,
+      eventPayloadName: event.eventPayloadName ?? name,
+      payload
+    });
+    const handler = identity === void 0 ? handlers[name] : eventTypeHandlers[identity.key] ?? handlers[name];
+    if (handler === void 0) throw new DcbDefinitionError("PROJECTOR_HANDLER_REQUIRED", `Projector ${id} has no handler for ${identity?.key ?? name}`);
+    const next = handler(state, definedEvent);
+    return assertJsonValue(next, "state-persistence");
+  };
+  const serializeState = options.serializeState ? (state) => {
+    assertJsonValue(state, "state-persistence");
+    const serialized = options.serializeState(state);
+    if (typeof serialized !== "string") throw new DcbDefinitionError("STATE_SERIALIZATION_INVALID", `Projector ${id} did not serialize to a string`);
+    return serialized;
+  } : (state) => JSON.stringify(assertJsonValue(state, "state-persistence"));
+  const deserializeState = options.deserializeState ? (serialized) => assertJsonValue(options.deserializeState(serialized), "state-persistence") : (serialized) => {
+    let parsed;
+    try {
+      parsed = JSON.parse(serialized);
+    } catch (error) {
+      throw new DcbDefinitionError("STATE_DESERIALIZATION_INVALID", `Projector ${id} received invalid JSON`, { cause: error });
+    }
+    return assertJsonValue(parsed, "state-persistence");
+  };
+  return Object.freeze({
+    id,
+    projectorId: id,
+    version,
+    projectorVersion: version,
+    subscribedEventNames: Object.freeze(uniqueSubscribed),
+    subscribedEventTypes: Object.freeze(uniqueSubscribedEventTypes),
+    initialState,
+    apply,
+    reduce: apply,
+    serializeState,
+    deserializeState
+  });
+}
+var done = (value, state) => Object.freeze({ kind: "committed", value, state });
+var noop = (reason) => Object.freeze({ kind: "noop", reason, events: [] });
+var reject = (reason, code = "command_rejected") => Object.freeze({ kind: "rejected", reason, code, events: [] });
+function defineCommand(options) {
+  const id = options.id ?? options.name;
+  if (!id) throw new DcbDefinitionError("COMMAND_ID_REQUIRED", "Command id is required");
+  const parser = options.parseInput ?? options.inputParser ?? options.input;
+  if (!parser) throw new DcbDefinitionError("COMMAND_INPUT_PARSER_REQUIRED", `Command ${id} requires an input parser`);
+  const parseInput = (input) => {
+    let parsed;
+    try {
+      parsed = parser(input);
+    } catch (error) {
+      throw new DcbDefinitionError("COMMAND_INPUT_INVALID", `Command ${id} input was rejected`, { cause: error });
+    }
+    assertJsonValue(parsed, "command-input");
+    return parsed;
+  };
+  const execute = (input, executionOptions) => {
+    const appended = [];
+    const stateMap = executionOptions?.state ?? {};
+    const context = {
+      state: (tag) => stateMap[defineTag(tag).id],
+      assertEmpty: (tag) => {
+        if (stateMap[defineTag(tag).id] !== void 0) throw new DcbDefinitionError("ASSERT_EMPTY_FAILED", `Tag ${defineTag(tag).id} is not empty`);
+      },
+      append: (event, payload, tags = []) => {
+        const entry = Object.freeze({ event, payload: event.parse(payload), tags: Object.freeze(tags.map((tag) => defineTag(tag))) });
+        appended.push(entry);
+        return entry;
+      },
+      done: (value) => Object.freeze({ kind: "committed", value }),
+      noop: (reason) => Object.freeze({ kind: "noop", reason }),
+      reject: (reason, code) => Object.freeze({ kind: "rejected", reason, code: code ?? "command_rejected" }),
+      appendedEvents: appended
+    };
+    const outcome = options.handler(parseInput(input), context);
+    if (!outcome || typeof outcome !== "object" || !["committed", "noop", "rejected"].includes(outcome.kind)) {
+      throw new DcbDefinitionError("COMMAND_OUTCOME_INVALID", `Command ${id} must return done, noop, or reject`);
+    }
+    if (outcome.kind === "committed") return Object.freeze({ ...outcome, events: Object.freeze([...appended]) });
+    if (appended.length > 0) throw new DcbDefinitionError("COMMAND_EVENTS_WITHOUT_COMMIT", `Command ${id} appended events but did not return done`);
+    return outcome.kind === "noop" ? Object.freeze({ ...outcome, events: [] }) : Object.freeze({ ...outcome, events: [] });
+  };
+  return Object.freeze({ id, name: id, parseInput, execute, handle: execute });
+}
+var DomainDefinitionError = class extends DcbDefinitionError {
+  code = "DOMAIN_DEFINITION_INVALID";
+  collisions;
+  constructor(collisions) {
+    super("DOMAIN_DEFINITION_INVALID", `Domain contains ${collisions.length} duplicate definition collision(s)`);
+    this.name = "DomainDefinitionError";
+    this.collisions = Object.freeze([...collisions]);
+  }
+};
+var componentId = (component) => component.id ?? component.name ?? "";
+var componentVersion = (component) => component.version ?? component.projectorVersion ?? component.queryVersion;
+function defineDomain(options) {
+  const events = [...options.events ?? []];
+  const commands = [...options.commands ?? []];
+  const projectors = [...options.projectors ?? []];
+  const queries = [...options.queries ?? []];
+  const materializedViews = [...options.materializedViews ?? options.mvs ?? []];
+  const collisions = [];
+  const collect = (kind, values) => {
+    const indexesById = /* @__PURE__ */ new Map();
+    values.forEach((id, index) => {
+      if (id.length === 0) return;
+      const indexes = indexesById.get(id) ?? [];
+      indexes.push(index);
+      indexesById.set(id, indexes);
+    });
+    for (const [id, indexes] of indexesById) {
+      if (indexes.length > 1) collisions.push({ kind, id, indexes: Object.freeze(indexes) });
+    }
+  };
+  collect("event-name", events.map((event) => event.name));
+  collect("command-id", commands.map((command) => command.id));
+  collect("projector-id", projectors.map((projector) => projector.id));
+  collect("query-id", queries.map(componentId));
+  collect("materialized-view-id", materializedViews.map(componentId));
+  const collectVersionPairs = (components, kind) => {
+    const pairs = /* @__PURE__ */ new Map();
+    components.forEach((component, index) => {
+      const id = componentId(component);
+      const version = componentVersion(component);
+      if (id.length === 0 || version === void 0) return;
+      const key = `${id}\0${version}`;
+      const indexes = pairs.get(key) ?? [];
+      indexes.push(index);
+      pairs.set(key, indexes);
+    });
+    for (const [key, indexes] of pairs) {
+      if (indexes.length > 1) {
+        const [id, version] = key.split("\0");
+        collisions.push({ kind, id, version: Number(version), indexes: Object.freeze(indexes) });
+      }
+    }
+  };
+  collectVersionPairs(projectors, "version-pair");
+  collectVersionPairs(queries, "version-pair");
+  collectVersionPairs(materializedViews, "version-pair");
+  if (collisions.length > 0) throw new DomainDefinitionError(collisions);
+  return Object.freeze({
+    events: Object.freeze(events),
+    commands: Object.freeze(commands),
+    projectors: Object.freeze(projectors),
+    queries: Object.freeze(queries),
+    materializedViews: Object.freeze(materializedViews),
+    eventByName: new Map(events.map((event) => [event.name, event]))
+  });
+}
+export {
+  CanonicalEventIdentityError,
+  DcbDefinitionError,
+  DomainDefinitionError,
+  JsonValidationError,
+  assertJsonValue,
+  canonicalEventKey,
+  defineCommand,
+  defineDomain,
+  defineEvent,
+  defineMaterializedView,
+  defineMaterializedViewRowMaterializer,
+  defineProjector,
+  defineRowMaterializer,
+  defineTag,
+  done,
+  noop,
+  parseCanonicalEventKey,
+  reject,
+  validateJsonValue
+};

package/dist/materializedView.d.ts

@@ -0,0 +1,107 @@
+import { type JsonValue } from "./index";
+/** The only scalar representations that may be persisted in an MV index. */
+export type MaterializedViewIndexValueType = "text" | "integer" | "real";
+export type MaterializedViewIndexValue = string | number;
+/** A finite, deploy-time index descriptor.  Its callback is pure by contract. */
+export interface MaterializedViewIndexDescriptor<TEvent = unknown> {
+    readonly id: string;
+    readonly valueType: MaterializedViewIndexValueType;
+    readonly value: (row: JsonValue, event: TEvent) => unknown;
+}
+export interface MaterializedViewRowUpsert {
+    readonly rowKey: string;
+    readonly value: JsonValue;
+    readonly rowVersion: number;
+    readonly sourceSuid: string;
+}
+export interface MaterializedViewRowDelete {
+    readonly rowKey: string;
+}
+/**
+ * A declarative partial-row mutation. The runtime applies `patch` with a
+ * database JSON function; it must not read/merge the row in TypeScript.
+ * When index entries are supplied, they replace this row's index entries in
+ * the same atomic batch. An empty list preserves existing entries.
+ */
+export interface MaterializedViewRowPatch {
+    readonly kind: "json_patch";
+    readonly rowKey: string;
+    readonly patch: JsonValue;
+    readonly rowVersion: number;
+    readonly sourceSuid: string;
+    readonly indexEntries: readonly MaterializedViewIndexEntryMutation[];
+}
+export interface MaterializedViewIndexEntryMutation {
+    readonly indexId: string;
+    readonly valueType: MaterializedViewIndexValueType;
+    readonly value: MaterializedViewIndexValue;
+    readonly rowKey: string;
+}
+export interface MaterializedViewIndexEntryDelete {
+    readonly indexId?: string;
+    readonly rowKey: string;
+}
+/**
+ * A complete deterministic write plan for one source event.  The runtime
+ * turns this value into prepared statements; no request-derived value is ever
+ * used as a SQL identifier.
+ */
+export interface MaterializedViewMutationPlan {
+    readonly rowUpserts: readonly MaterializedViewRowUpsert[];
+    readonly rowDeletes: readonly MaterializedViewRowDelete[];
+    readonly rowPatches: readonly MaterializedViewRowPatch[];
+    readonly indexEntries: readonly MaterializedViewIndexEntryMutation[];
+    readonly indexDeletes: readonly MaterializedViewIndexEntryDelete[];
+}
+export interface MaterializedViewRowMaterializerOptions<TEvent = unknown> {
+    readonly id: string;
+    readonly version?: number;
+    readonly indexDescriptors?: readonly MaterializedViewIndexDescriptor<TEvent>[];
+    readonly indexes?: readonly MaterializedViewIndexDescriptor<TEvent>[];
+    /** Return row upserts/deletes, or a complete plan when custom indexes are needed. */
+    readonly materialize?: (event: TEvent) => MaterializedViewMaterializeResult;
+    readonly plan?: (event: TEvent) => MaterializedViewMaterializeResult;
+}
+export type MaterializedViewMaterializeResult = {
+    readonly rowUpserts?: readonly MaterializedViewRowInput[];
+    readonly upserts?: readonly MaterializedViewRowInput[];
+    readonly rowDeletes?: readonly (string | MaterializedViewRowDelete)[];
+    readonly deletes?: readonly (string | MaterializedViewRowDelete)[];
+    readonly rowPatches?: readonly MaterializedViewRowPatchInput[];
+    readonly patches?: readonly MaterializedViewRowPatchInput[];
+    readonly indexEntries?: readonly MaterializedViewIndexEntryInput[];
+    readonly indexDeletes?: readonly MaterializedViewIndexEntryDelete[];
+} | MaterializedViewMutationPlan;
+export interface MaterializedViewRowInput {
+    readonly rowKey: string;
+    readonly value: unknown;
+    readonly rowVersion?: number;
+    readonly sourceSuid?: string;
+}
+export interface MaterializedViewRowPatchInput {
+    readonly kind: "json_patch";
+    readonly rowKey: string;
+    readonly patch: unknown;
+    readonly rowVersion?: number;
+    readonly sourceSuid?: string;
+    readonly indexEntries?: readonly MaterializedViewIndexEntryInput[];
+}
+export interface MaterializedViewIndexEntryInput {
+    readonly indexId: string;
+    readonly valueType?: MaterializedViewIndexValueType;
+    readonly value: unknown;
+    readonly rowKey: string;
+}
+export interface MaterializedViewRowMaterializer<TEvent = unknown> {
+    readonly id: string;
+    readonly version: number;
+    readonly indexDescriptors: readonly MaterializedViewIndexDescriptor<TEvent>[];
+    readonly plan: (event: TEvent) => MaterializedViewMutationPlan;
+    readonly planFor: (event: TEvent) => MaterializedViewMutationPlan;
+    readonly mutationPlan: (event: TEvent) => MaterializedViewMutationPlan;
+}
+export type RowMaterializerDefinition<TEvent = unknown> = MaterializedViewRowMaterializer<TEvent>;
+/** Define a finite, JSON-validating, deterministic row materializer. */
+export declare function defineRowMaterializer<TEvent = unknown>(options: MaterializedViewRowMaterializerOptions<TEvent>): MaterializedViewRowMaterializer<TEvent>;
+export declare const defineMaterializedView: typeof defineRowMaterializer;
+export declare const defineMaterializedViewRowMaterializer: typeof defineRowMaterializer;

package/dist/materializedView.js

@@ -0,0 +1,173 @@
+import { assertJsonValue } from "./index";
+function nonEmpty(value, code, message) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error(`${code}: ${message}`);
+}
+function descriptorValue(descriptor, value) {
+    if (descriptor.valueType === "text") {
+        if (typeof value !== "string")
+            throw new Error(`MV index ${descriptor.id} expected a text value`);
+        return value;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`MV index ${descriptor.id} expected a finite numeric value`);
+    }
+    if (descriptor.valueType === "integer" && (!Number.isSafeInteger(value) || !Number.isInteger(value))) {
+        throw new Error(`MV index ${descriptor.id} expected a safe integer value`);
+    }
+    return value;
+}
+function validateDescriptors(descriptors) {
+    const seen = new Set();
+    for (const descriptor of descriptors) {
+        nonEmpty(descriptor.id, "MV_INDEX_ID_REQUIRED", "Index descriptor id is required");
+        if (seen.has(descriptor.id))
+            throw new Error(`MV_INDEX_DUPLICATE: ${descriptor.id}`);
+        seen.add(descriptor.id);
+        if (!["text", "integer", "real"].includes(descriptor.valueType)) {
+            throw new Error(`MV_INDEX_VALUE_TYPE_INVALID: ${descriptor.id}`);
+        }
+        if (typeof descriptor.value !== "function")
+            throw new Error(`MV_INDEX_VALUE_REQUIRED: ${descriptor.id}`);
+    }
+    return Object.freeze(descriptors.map((descriptor) => Object.freeze({ ...descriptor })));
+}
+function normalizeRowInput(input, event) {
+    nonEmpty(input.rowKey, "MV_ROW_KEY_REQUIRED", "Row key is required");
+    const value = assertJsonValue(input.value, "state-persistence");
+    const rowVersion = input.rowVersion ?? 1;
+    if (!Number.isSafeInteger(rowVersion) || rowVersion < 0)
+        throw new Error(`MV_ROW_VERSION_INVALID: ${input.rowKey}`);
+    const sourceSuid = input.sourceSuid ?? (typeof event === "object" && event !== null && "suid" in event && typeof event.suid === "string"
+        ? event.suid
+        : "");
+    nonEmpty(sourceSuid, "MV_SOURCE_SUID_REQUIRED", `Source SUID is required for ${input.rowKey}`);
+    return Object.freeze({ rowKey: input.rowKey, value, rowVersion, sourceSuid });
+}
+function normalizeRowDeletes(values = []) {
+    const keys = new Set();
+    for (const value of values) {
+        const rowKey = typeof value === "string" ? value : value.rowKey;
+        nonEmpty(rowKey, "MV_ROW_KEY_REQUIRED", "Row delete key is required");
+        keys.add(rowKey);
+    }
+    return Object.freeze([...keys].map((rowKey) => Object.freeze({ rowKey })));
+}
+function normalizeIndexEntries(values, descriptors, rowKey) {
+    const descriptorById = new Map(descriptors.map((descriptor) => [descriptor.id, descriptor]));
+    return Object.freeze(values.map((entry) => {
+        nonEmpty(entry.indexId, "MV_INDEX_ID_REQUIRED", "Index entry id is required");
+        const descriptor = descriptorById.get(entry.indexId);
+        if (descriptor === undefined)
+            throw new Error(`MV_INDEX_UNDECLARED: ${entry.indexId}`);
+        nonEmpty(entry.rowKey, "MV_ROW_KEY_REQUIRED", "Index entry row key is required");
+        if (rowKey !== undefined && entry.rowKey !== rowKey) {
+            throw new Error(`MV_INDEX_ROW_KEY_MISMATCH: ${entry.indexId}`);
+        }
+        const valueType = entry.valueType ?? descriptor.valueType;
+        if (valueType !== descriptor.valueType)
+            throw new Error(`MV_INDEX_VALUE_TYPE_MISMATCH: ${entry.indexId}`);
+        return Object.freeze({
+            indexId: entry.indexId,
+            valueType,
+            value: descriptorValue(descriptor, entry.value),
+            rowKey: entry.rowKey,
+        });
+    }));
+}
+function normalizeRowPatches(values, descriptors, event) {
+    return Object.freeze(values.map((input) => {
+        nonEmpty(input.rowKey, "MV_ROW_KEY_REQUIRED", "Row patch key is required");
+        if (input.kind !== "json_patch")
+            throw new Error(`MV_PATCH_KIND_INVALID: ${input.rowKey}`);
+        const patch = assertJsonValue(input.patch, "state-persistence");
+        if (typeof patch !== "object" || patch === null || Array.isArray(patch)) {
+            throw new Error(`MV_PATCH_OBJECT_REQUIRED: ${input.rowKey}`);
+        }
+        const rowVersion = input.rowVersion ?? 1;
+        if (!Number.isSafeInteger(rowVersion) || rowVersion < 0)
+            throw new Error(`MV_ROW_VERSION_INVALID: ${input.rowKey}`);
+        const sourceSuid = input.sourceSuid ?? (typeof event === "object" && event !== null && "suid" in event && typeof event.suid === "string"
+            ? event.suid
+            : "");
+        nonEmpty(sourceSuid, "MV_SOURCE_SUID_REQUIRED", `Source SUID is required for ${input.rowKey}`);
+        return Object.freeze({
+            kind: "json_patch",
+            rowKey: input.rowKey,
+            patch,
+            rowVersion,
+            sourceSuid,
+            indexEntries: normalizeIndexEntries(input.indexEntries ?? [], descriptors, input.rowKey),
+        });
+    }));
+}
+function normalizePlan(result, descriptors, event) {
+    const value = result;
+    const rawUpserts = (value.rowUpserts ?? value.upserts ?? []);
+    const rawDeletes = (value.rowDeletes ?? value.deletes ?? []);
+    const rawPatches = (value.rowPatches ?? value.patches ?? []);
+    const rowUpserts = rawUpserts.map((row) => normalizeRowInput(row, event));
+    const rowDeletes = normalizeRowDeletes(rawDeletes);
+    const rowPatches = normalizeRowPatches(rawPatches, descriptors, event);
+    const descriptorById = new Map(descriptors.map((descriptor) => [descriptor.id, descriptor]));
+    const explicitEntries = (value.indexEntries ?? []);
+    const generatedEntries = [];
+    for (const row of rowUpserts) {
+        for (const descriptor of descriptors) {
+            let candidate;
+            try {
+                candidate = descriptor.value(row.value, event);
+            }
+            catch (error) {
+                throw new Error(`MV_INDEX_VALUE_FAILED: ${descriptor.id}: ${String(error)}`);
+            }
+            if (candidate === undefined || candidate === null)
+                continue;
+            generatedEntries.push(Object.freeze({
+                indexId: descriptor.id,
+                valueType: descriptor.valueType,
+                value: descriptorValue(descriptor, candidate),
+                rowKey: row.rowKey,
+            }));
+        }
+    }
+    generatedEntries.push(...normalizeIndexEntries(explicitEntries, descriptors));
+    const indexDeletes = Object.freeze((value.indexDeletes ?? []).map((entry) => {
+        nonEmpty(entry.rowKey, "MV_ROW_KEY_REQUIRED", "Index delete row key is required");
+        if (entry.indexId !== undefined) {
+            nonEmpty(entry.indexId, "MV_INDEX_ID_REQUIRED", "Index delete id is required");
+            if (!descriptorById.has(entry.indexId))
+                throw new Error(`MV_INDEX_UNDECLARED: ${entry.indexId}`);
+        }
+        return Object.freeze({ indexId: entry.indexId, rowKey: entry.rowKey });
+    }));
+    return Object.freeze({
+        rowUpserts: Object.freeze(rowUpserts),
+        rowDeletes,
+        rowPatches,
+        indexEntries: Object.freeze(generatedEntries),
+        indexDeletes,
+    });
+}
+/** Define a finite, JSON-validating, deterministic row materializer. */
+export function defineRowMaterializer(options) {
+    nonEmpty(options.id, "MV_ID_REQUIRED", "Materialized-view id is required");
+    const version = options.version ?? 1;
+    if (!Number.isSafeInteger(version) || version < 1)
+        throw new Error("MV_VERSION_INVALID: version must be positive");
+    const descriptors = validateDescriptors(options.indexDescriptors ?? options.indexes ?? []);
+    const materialize = options.materialize ?? options.plan;
+    if (typeof materialize !== "function")
+        throw new Error(`MV_MATERIALIZER_REQUIRED: ${options.id}`);
+    const plan = (event) => normalizePlan(materialize(event), descriptors, event);
+    return Object.freeze({
+        id: options.id,
+        version,
+        indexDescriptors: descriptors,
+        plan,
+        planFor: plan,
+        mutationPlan: plan,
+    });
+}
+export const defineMaterializedView = defineRowMaterializer;
+export const defineMaterializedViewRowMaterializer = defineRowMaterializer;

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@sekiban/dcb-core",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Cloudflare-independent Serialized DCB definitions and domain algebra.",
+  "license": "Elastic-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/J-Tech-Japan/sekiban-dcb-ts.git",
+    "directory": "packages/dcb-core"
+  },
+  "homepage": "https://github.com/J-Tech-Japan/sekiban-dcb-ts/tree/main/packages/dcb-core#readme",
+  "bugs": {
+    "url": "https://github.com/J-Tech-Japan/sekiban-dcb-ts/issues"
+  },
+  "keywords": [
+    "sekiban",
+    "dcb",
+    "core",
+    "serialized-dcb"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && esbuild src/index.ts --bundle --format=esm --platform=neutral --outfile=dist/index.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}