hikoutei 0.2.0

package/dist/application/orm/api/contracts.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Public lifecycle contracts for the typed-sheets ORM facade.
+ *
+ * They intentionally describe our entity lifecycle rather than any concrete
+ * ORM implementation, so a SQLite execution adapter can change without
+ * changing the application's `em.persist()` / `em.flush()` workflow.
+ */
+import { type Presence } from "../../../shared/state/index.js";
+import type { SqlExecutor } from "../../../adapter/persistence/contracts/sql.js";
+/** Constructor accepted by the initial entity-style public API. */
+export interface TypedSheetsEntityClass<Entity extends object> {
+    new (...arguments_: never[]): Entity;
+}
+/** Stable entity reference accepted by our EntityManager facade. */
+export type TypedSheetsEntityReference<Entity extends object> = string | TypedSheetsEntityClass<Entity>;
+/** Values used when creating one entity through `em.create()`. */
+export type TypedSheetsEntityData<Entity extends object> = Readonly<Partial<Entity>>;
+/** Equality filter accepted by the initial `find()` and `findOne()` surface. */
+export type TypedSheetsEntityFilter<Entity extends object> = Readonly<Partial<Entity>>;
+/** Read options intentionally supported by the initial public entity API. */
+export interface TypedSheetsFindOptions {
+    readonly limit?: number;
+    readonly offset?: number;
+}
+/** Entity-manager fork behavior supported without leaking the underlying ORM. */
+export interface TypedSheetsForkOptions {
+    /** Starts the fork with an empty identity map when the execution engine supports it. */
+    readonly clear?: boolean;
+}
+/** Callback invoked by one entity execution engine immediately before it writes. */
+export type TypedSheetsEntityFlushListener = (context: TypedSheetsFlushContext) => Promise<void>;
+/**
+ * Replaceable internal execution engine for the typed-sheets EntityManager.
+ *
+ * This is the only extension point an ORM-specific integration must implement.
+ * It deliberately uses typed-sheets lifecycle types, never MikroORM types.
+ */
+export interface TypedSheetsEntityEngine {
+    /** Opens an isolated manager for one request, job, or unit of work. */
+    fork(): TypedSheetsEntityEngineManager;
+    /** Releases resources owned by the underlying SQLite execution engine. */
+    close(force?: boolean): Promise<void>;
+}
+/** Internal manager operations required to implement the public entity lifecycle. */
+export interface TypedSheetsEntityEngineManager {
+    fork(options?: TypedSheetsForkOptions): TypedSheetsEntityEngineManager;
+    create<Entity extends object>(entityName: TypedSheetsEntityReference<Entity>, data: TypedSheetsEntityData<Entity>): Entity;
+    find<Entity extends object>(entityName: TypedSheetsEntityReference<Entity>, where: TypedSheetsEntityFilter<Entity>, options?: TypedSheetsFindOptions): Promise<readonly Entity[]>;
+    findOne<Entity extends object>(entityName: TypedSheetsEntityReference<Entity>, where: TypedSheetsEntityFilter<Entity>, options?: TypedSheetsFindOptions): Promise<Entity | null>;
+    persist<Entity extends object>(entity: Entity | Iterable<Entity>): void;
+    remove<Entity extends object>(entity: Entity | Iterable<Entity>): void;
+    flush(): Promise<void>;
+    transactional<Result>(operation: (entityManager: TypedSheetsEntityEngineManager) => Promise<Result>): Promise<Result>;
+    clear(): void;
+    isInTransaction(): boolean;
+    begin(): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    /** Registers the typed-sheets plan to run in the engine's active flush transaction. */
+    onFlush(listener: TypedSheetsEntityFlushListener): void;
+}
+/** Runtime values for durable entity changes observed during one flush. */
+export declare const TYPED_SHEETS_ENTITY_CHANGE_KINDS: {
+    readonly CREATE: "create";
+    readonly UPDATE: "update";
+    readonly DELETE: "delete";
+};
+/** Closed set of entity lifecycle changes handled by the typed-sheets ORM. */
+export type TypedSheetsEntityChangeKind = (typeof TYPED_SHEETS_ENTITY_CHANGE_KINDS)[keyof typeof TYPED_SHEETS_ENTITY_CHANGE_KINDS];
+/** Values captured from one MikroORM changeset before it reaches persistence. */
+export type TypedSheetsEntityChangePayload = Readonly<Record<string, unknown>>;
+/** Shared data carried by every normalized entity lifecycle change. */
+export interface TypedSheetsEntityChangeBase {
+    readonly entityName: string;
+    readonly entity: object;
+    readonly primaryKey: Presence<string>;
+    /** Changed scalar values for updates and persisted values for inserts. */
+    readonly payload: TypedSheetsEntityChangePayload;
+}
+/** Entity was newly managed and will be inserted during the current flush. */
+export interface TypedSheetsCreatedEntityChange extends TypedSheetsEntityChangeBase {
+    readonly kind: typeof TYPED_SHEETS_ENTITY_CHANGE_KINDS.CREATE;
+}
+/** Existing entity fields changed during the current flush. */
+export interface TypedSheetsUpdatedEntityChange extends TypedSheetsEntityChangeBase {
+    readonly kind: typeof TYPED_SHEETS_ENTITY_CHANGE_KINDS.UPDATE;
+}
+/** Existing entity was marked for removal during the current flush. */
+export interface TypedSheetsDeletedEntityChange extends TypedSheetsEntityChangeBase {
+    readonly kind: typeof TYPED_SHEETS_ENTITY_CHANGE_KINDS.DELETE;
+}
+/**
+ * One normalized entity change collected from a single `flush()` operation.
+ *
+ * The discriminant keeps lifecycle branching explicit for coordinators while
+ * the adapter-specific changeset shape remains outside the public contract.
+ */
+export type TypedSheetsEntityChange = TypedSheetsCreatedEntityChange | TypedSheetsUpdatedEntityChange | TypedSheetsDeletedEntityChange;
+/** Context available to the typed-sheets sync planner during an entity flush. */
+export interface TypedSheetsFlushContext {
+    /** All entity changes in the current Unit of Work(작업 단위). */
+    readonly changes: readonly TypedSheetsEntityChange[];
+    /** SQL executor bound to the same transaction as the entity writes. */
+    readonly sql: SqlExecutor;
+}
+/**
+ * Converts durable entity changes into typed-sheets canonical and outbox work.
+ *
+ * The coordinator runs before entity rows are flushed, but within the same
+ * SQLite transaction. Throwing aborts both the entity write and every
+ * typed-sheets write scheduled through `context.sql`.
+ */
+export interface TypedSheetsFlushCoordinator {
+    onFlush(context: TypedSheetsFlushContext): Promise<void>;
+}
+/** Converts a database-generated primary-key value into the public presence contract. */
+export declare function primaryKeyPresence(primaryKey: string | null): Presence<string>;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/application/orm/api/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../../../src/application/orm/api/contracts.ts"],"names":[],"mappings":"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"}

package/dist/application/orm/api/contracts.js

@@ -0,0 +1,21 @@
+/**
+ * Public lifecycle contracts for the typed-sheets ORM facade.
+ *
+ * They intentionally describe our entity lifecycle rather than any concrete
+ * ORM implementation, so a SQLite execution adapter can change without
+ * changing the application's `em.persist()` / `em.flush()` workflow.
+ */
+import { PRESENCE_KINDS, } from "../../../shared/state/index.js";
+/** Runtime values for durable entity changes observed during one flush. */
+export const TYPED_SHEETS_ENTITY_CHANGE_KINDS = {
+    CREATE: "create",
+    UPDATE: "update",
+    DELETE: "delete",
+};
+/** Converts a database-generated primary-key value into the public presence contract. */
+export function primaryKeyPresence(primaryKey) {
+    return primaryKey === null
+        ? { kind: PRESENCE_KINDS.ABSENT }
+        : { kind: PRESENCE_KINDS.PRESENT, value: primaryKey };
+}
+//# sourceMappingURL=contracts.js.map

package/dist/application/orm/api/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../../../src/application/orm/api/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,cAAc,GAEf,MAAM,gCAAgC,CAAC;AAiFxC,2EAA2E;AAC3E,MAAM,CAAC,MAAM,gCAAgC,GAAG;IAC9C,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;CACR,CAAC;AA+DX,yFAAyF;AACzF,MAAM,UAAU,kBAAkB,CAAC,UAAyB;IAC1D,OAAO,UAAU,KAAK,IAAI;QACxB,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,MAAM,EAAE;QACjC,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AAC1D,CAAC"}

package/dist/application/orm/errors.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Structured errors raised by the public typed-sheets ORM composition layer.
+ *
+ * Storage failures retain their existing `StorageError` contract. These codes
+ * describe configuration or lifecycle failures before a storage primitive can
+ * safely continue.
+ */
+import { CoreErrorException } from "../../domain/errors/index.js";
+/** Stable codes emitted by entity mapping and mapped lifecycle helpers. */
+export declare const TYPED_SHEETS_ORM_ERROR_CODES: {
+    readonly INVALID_ENTITY_MAPPING: "invalid_entity_mapping";
+    readonly DUPLICATE_ENTITY_MAPPING: "duplicate_entity_mapping";
+    readonly ENTITY_MAPPING_NOT_FOUND: "entity_mapping_not_found";
+    readonly ENTITY_PRIMARY_KEY_UNAVAILABLE: "entity_primary_key_unavailable";
+    readonly ENTITY_PRIMARY_KEY_MISMATCH: "entity_primary_key_mismatch";
+    readonly ENTITY_PRIMARY_KEY_MUTATION: "entity_primary_key_mutation";
+    readonly INVALID_MAPPED_FIELD_VALUE: "invalid_mapped_field_value";
+    readonly WRITER_LEASE_UNAVAILABLE: "writer_lease_unavailable";
+    readonly ROW_BINDING_CONFLICT: "row_binding_conflict";
+    readonly CANONICAL_COMMIT_REJECTED: "canonical_commit_rejected";
+    readonly PROJECTION_OUTBOX_BLOCKED: "projection_outbox_blocked";
+    readonly OBSERVATION_ENTITY_MUTATION_FAILED: "observation_entity_mutation_failed";
+};
+/** Closed set of typed-sheets ORM composition error codes. */
+export type TypedSheetsOrmErrorCode = (typeof TYPED_SHEETS_ORM_ERROR_CODES)[keyof typeof TYPED_SHEETS_ORM_ERROR_CODES];
+/**
+ * Error raised when mapping metadata or its lifecycle plan is unsafe.
+ *
+ * The stable `code` lets applications distinguish a bad entity mapping from a
+ * temporary writer-lease race without parsing an English error message.
+ */
+export declare class TypedSheetsOrmError extends CoreErrorException<"typed_sheets_orm", TypedSheetsOrmErrorCode> {
+    constructor(code: TypedSheetsOrmErrorCode, message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/application/orm/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/application/orm/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAElE,2EAA2E;AAC3E,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;CAa/B,CAAC;AAEX,8DAA8D;AAC9D,MAAM,MAAM,uBAAuB,GACjC,CAAC,OAAO,4BAA4B,CAAC,CAAC,MAAM,OAAO,4BAA4B,CAAC,CAAC;AAEnF;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,kBAAkB,CACzD,kBAAkB,EAClB,uBAAuB,CACxB;gBACa,IAAI,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM;CAG3D"}

package/dist/application/orm/errors.js

@@ -0,0 +1,35 @@
+/**
+ * Structured errors raised by the public typed-sheets ORM composition layer.
+ *
+ * Storage failures retain their existing `StorageError` contract. These codes
+ * describe configuration or lifecycle failures before a storage primitive can
+ * safely continue.
+ */
+import { CoreErrorException } from "../../domain/errors/index.js";
+/** Stable codes emitted by entity mapping and mapped lifecycle helpers. */
+export const TYPED_SHEETS_ORM_ERROR_CODES = {
+    INVALID_ENTITY_MAPPING: "invalid_entity_mapping",
+    DUPLICATE_ENTITY_MAPPING: "duplicate_entity_mapping",
+    ENTITY_MAPPING_NOT_FOUND: "entity_mapping_not_found",
+    ENTITY_PRIMARY_KEY_UNAVAILABLE: "entity_primary_key_unavailable",
+    ENTITY_PRIMARY_KEY_MISMATCH: "entity_primary_key_mismatch",
+    ENTITY_PRIMARY_KEY_MUTATION: "entity_primary_key_mutation",
+    INVALID_MAPPED_FIELD_VALUE: "invalid_mapped_field_value",
+    WRITER_LEASE_UNAVAILABLE: "writer_lease_unavailable",
+    ROW_BINDING_CONFLICT: "row_binding_conflict",
+    CANONICAL_COMMIT_REJECTED: "canonical_commit_rejected",
+    PROJECTION_OUTBOX_BLOCKED: "projection_outbox_blocked",
+    OBSERVATION_ENTITY_MUTATION_FAILED: "observation_entity_mutation_failed",
+};
+/**
+ * Error raised when mapping metadata or its lifecycle plan is unsafe.
+ *
+ * The stable `code` lets applications distinguish a bad entity mapping from a
+ * temporary writer-lease race without parsing an English error message.
+ */
+export class TypedSheetsOrmError extends CoreErrorException {
+    constructor(code, message) {
+        super("typed_sheets_orm", code, message);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/application/orm/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/application/orm/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAElE,2EAA2E;AAC3E,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,sBAAsB,EAAE,wBAAwB;IAChD,wBAAwB,EAAE,0BAA0B;IACpD,wBAAwB,EAAE,0BAA0B;IACpD,8BAA8B,EAAE,gCAAgC;IAChE,2BAA2B,EAAE,6BAA6B;IAC1D,2BAA2B,EAAE,6BAA6B;IAC1D,0BAA0B,EAAE,4BAA4B;IACxD,wBAAwB,EAAE,0BAA0B;IACpD,oBAAoB,EAAE,sBAAsB;IAC5C,yBAAyB,EAAE,2BAA2B;IACtD,yBAAyB,EAAE,2BAA2B;IACtD,kCAAkC,EAAE,oCAAoC;CAChE,CAAC;AAMX;;;;;GAKG;AACH,MAAM,OAAO,mBAAoB,SAAQ,kBAGxC;IACC,YAAY,IAA6B,EAAE,OAAe;QACxD,KAAK,CAAC,kBAAkB,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAC3C,CAAC;CACF"}

package/dist/application/orm/index.d.ts

@@ -0,0 +1,13 @@
+export { TYPED_SHEETS_ENTITY_CHANGE_KINDS, primaryKeyPresence, } from "./api/contracts.js";
+export { createTypedSheetsOrm, TypedSheetsEntityManager, TypedSheetsOrm, } from "./api/TypedSheetsOrm.js";
+export { createTypedSheetsEntityMappingRegistry, createTypedSheetsEntityOwnershipManifest, createTypedSheetsEntityProjectionRegistration, createTypedSheetsMappedProjectionDefinitions, decodeTypedSheetsEntityField, defineTypedSheetsEntityMapping, encodeTypedSheetsEntity, encodeTypedSheetsEntityField, requireTypedSheetsEntityField, requireTypedSheetsEntityProjection, serializeTypedSheetsEntityOwnershipManifest, typedSheetsEntityAnchor, typedSheetsEntityId, typedSheetsEntityProjectionHeaders, typedSheetsEntityRowBindingId, } from "./mapping/entityMapping.js";
+export { TYPED_SHEETS_ORM_ERROR_CODES, TypedSheetsOrmError, } from "./errors.js";
+export { createMappedTypedSheetsFlushCoordinator, registeredTypedSheetsProjectionDefinitions, registerTypedSheetsEntityMappings, } from "./persistence/flush/mappedFlushCoordinator.js";
+export { MAPPED_OBSERVATION_ENTITY_MUTATION_KINDS, planMappedObservationEntityMutation, } from "./mapping/observationMapping.js";
+export type { TypedSheetsEntityClass, TypedSheetsEntityChange, TypedSheetsEntityChangeBase, TypedSheetsEntityChangeKind, TypedSheetsEntityChangePayload, TypedSheetsCreatedEntityChange, TypedSheetsDeletedEntityChange, TypedSheetsEntityData, TypedSheetsEntityEngine, TypedSheetsEntityEngineManager, TypedSheetsEntityFilter, TypedSheetsEntityFlushListener, TypedSheetsEntityReference, TypedSheetsFindOptions, TypedSheetsForkOptions, TypedSheetsFlushContext, TypedSheetsFlushCoordinator, TypedSheetsUpdatedEntityChange, } from "./api/contracts.js";
+export type { CreateTypedSheetsOrmOptions } from "./api/TypedSheetsOrm.js";
+export type { CreateMappedTypedSheetsFlushCoordinatorOptions, RegisteredTypedSheetsMappedProjection, TypedSheetsEntityWriterOptions, } from "./persistence/flush/mappedFlushCoordinator.js";
+export type { MappedObservationEntityMutation } from "./mapping/observationMapping.js";
+export type { TypedSheetsEntityFieldCodec, TypedSheetsEntityFieldMapping, TypedSheetsEntityFieldMappingInput, TypedSheetsEntityMapping, TypedSheetsEntityMappingInput, TypedSheetsEntityMappingRegistry, TypedSheetsEntityProjection, TypedSheetsEntityProjectionMapping, TypedSheetsEntityProjectionMappingInput, TypedSheetsEntityProperty, TypedSheetsMappedProjectionDefinition, } from "./mapping/entityMapping.js";
+export type { TypedSheetsOrmErrorCode } from "./errors.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/application/orm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/application/orm/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gCAAgC,EAChC,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,oBAAoB,EACpB,wBAAwB,EACxB,cAAc,GACf,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,sCAAsC,EACtC,wCAAwC,EACxC,6CAA6C,EAC7C,4CAA4C,EAC5C,4BAA4B,EAC5B,8BAA8B,EAC9B,uBAAuB,EACvB,4BAA4B,EAC5B,6BAA6B,EAC7B,kCAAkC,EAClC,2CAA2C,EAC3C,uBAAuB,EACvB,mBAAmB,EACnB,kCAAkC,EAClC,6BAA6B,GAC9B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,4BAA4B,EAC5B,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,uCAAuC,EACvC,0CAA0C,EAC1C,iCAAiC,GAClC,MAAM,+CAA+C,CAAC;AACvD,OAAO,EACL,wCAAwC,EACxC,mCAAmC,GACpC,MAAM,iCAAiC,CAAC;AACzC,YAAY,EACV,sBAAsB,EACtB,uBAAuB,EACvB,2BAA2B,EAC3B,2BAA2B,EAC3B,8BAA8B,EAC9B,8BAA8B,EAC9B,8BAA8B,EAC9B,qBAAqB,EACrB,uBAAuB,EACvB,8BAA8B,EAC9B,uBAAuB,EACvB,8BAA8B,EAC9B,0BAA0B,EAC1B,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,2BAA2B,EAC3B,8BAA8B,GAC/B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAC3E,YAAY,EACV,8CAA8C,EAC9C,qCAAqC,EACrC,8BAA8B,GAC/B,MAAM,+CAA+C,CAAC;AACvD,YAAY,EAAE,+BAA+B,EAAE,MAAM,iCAAiC,CAAC;AACvF,YAAY,EACV,2BAA2B,EAC3B,6BAA6B,EAC7B,kCAAkC,EAClC,wBAAwB,EACxB,6BAA6B,EAC7B,gCAAgC,EAChC,2BAA2B,EAC3B,kCAAkC,EAClC,uCAAuC,EACvC,yBAAyB,EACzB,qCAAqC,GACtC,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC"}

package/dist/application/orm/index.js

@@ -0,0 +1,7 @@
+export { TYPED_SHEETS_ENTITY_CHANGE_KINDS, primaryKeyPresence, } from "./api/contracts.js";
+export { createTypedSheetsOrm, TypedSheetsEntityManager, TypedSheetsOrm, } from "./api/TypedSheetsOrm.js";
+export { createTypedSheetsEntityMappingRegistry, createTypedSheetsEntityOwnershipManifest, createTypedSheetsEntityProjectionRegistration, createTypedSheetsMappedProjectionDefinitions, decodeTypedSheetsEntityField, defineTypedSheetsEntityMapping, encodeTypedSheetsEntity, encodeTypedSheetsEntityField, requireTypedSheetsEntityField, requireTypedSheetsEntityProjection, serializeTypedSheetsEntityOwnershipManifest, typedSheetsEntityAnchor, typedSheetsEntityId, typedSheetsEntityProjectionHeaders, typedSheetsEntityRowBindingId, } from "./mapping/entityMapping.js";
+export { TYPED_SHEETS_ORM_ERROR_CODES, TypedSheetsOrmError, } from "./errors.js";
+export { createMappedTypedSheetsFlushCoordinator, registeredTypedSheetsProjectionDefinitions, registerTypedSheetsEntityMappings, } from "./persistence/flush/mappedFlushCoordinator.js";
+export { MAPPED_OBSERVATION_ENTITY_MUTATION_KINDS, planMappedObservationEntityMutation, } from "./mapping/observationMapping.js";
+//# sourceMappingURL=index.js.map

package/dist/application/orm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/application/orm/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gCAAgC,EAChC,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,oBAAoB,EACpB,wBAAwB,EACxB,cAAc,GACf,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,sCAAsC,EACtC,wCAAwC,EACxC,6CAA6C,EAC7C,4CAA4C,EAC5C,4BAA4B,EAC5B,8BAA8B,EAC9B,uBAAuB,EACvB,4BAA4B,EAC5B,6BAA6B,EAC7B,kCAAkC,EAClC,2CAA2C,EAC3C,uBAAuB,EACvB,mBAAmB,EACnB,kCAAkC,EAClC,6BAA6B,GAC9B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,4BAA4B,EAC5B,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,uCAAuC,EACvC,0CAA0C,EAC1C,iCAAiC,GAClC,MAAM,+CAA+C,CAAC;AACvD,OAAO,EACL,wCAAwC,EACxC,mCAAmC,GACpC,MAAM,iCAAiC,CAAC"}

package/dist/application/orm/mapping/contracts.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Type contracts for entity-to-Sheets mappings.
+ *
+ * This file contains declarations only. Validation, indexing, projection
+ * registration, and value conversion live in their respective modules.
+ */
+import { type FieldOwnership, type NormalizedCell } from "../../../domain/index.js";
+import { SYNC_GATEWAY_PROJECTIONS } from "../../sync/gateway/constants.js";
+import type { RegisterSyncSheetInput } from "../../../infrastructure/storage/index.js";
+import type { TypedSheetsEntityReference } from "../api/contracts.js";
+import type { NormalizedCellKind } from "../../../shared/encoding/constants.js";
+/** Physical projections supported by a mapped business entity. */
+export type TypedSheetsEntityProjection = typeof SYNC_GATEWAY_PROJECTIONS.USER_INPUT | typeof SYNC_GATEWAY_PROJECTIONS.SYSTEM_STATE;
+/** A string property name declared by one mapped entity. */
+export type TypedSheetsEntityProperty<Entity extends object> = Extract<keyof Entity, string>;
+/** Optional codec used when a TypeScript property needs custom cell conversion. */
+export interface TypedSheetsEntityFieldCodec {
+    /** Converts one entity property value into a normalized Sheet cell. */
+    readonly encode?: (value: unknown) => NormalizedCell;
+    /** Converts one accepted canonical cell into an entity property value. */
+    readonly decode?: (value: NormalizedCell) => unknown;
+}
+/** Input declaration for one entity property stored as a canonical field. */
+export interface TypedSheetsEntityFieldMappingInput<Entity extends object> extends TypedSheetsEntityFieldCodec {
+    /** Property on the application entity. */
+    readonly property: TypedSheetsEntityProperty<Entity>;
+    /** Stable canonical/Sheet field name. Defaults to `property`. */
+    readonly fieldName?: string;
+    /** Runtime cell type stored in canonical state and projected to Sheets. */
+    readonly cellKind: NormalizedCellKind;
+    /** Whether a human Sheet edit may own this business field. */
+    readonly ownership: FieldOwnership;
+    /** Whether blank (`null`) or an empty string is invalid. */
+    readonly required?: boolean;
+    /** Whether this is the one v1 business-key field. */
+    readonly unique?: boolean;
+}
+/** Immutable routing coordinates for one physical User_Input or System_State tab. */
+export interface TypedSheetsEntityProjectionMappingInput {
+    readonly physicalSheetId: string;
+    readonly spreadsheetId: string;
+    readonly tabName: string;
+    readonly registeredRange: string;
+    readonly projection: TypedSheetsEntityProjection;
+}
+/** User-facing declaration used to construct one validated entity mapping. */
+export interface TypedSheetsEntityMappingInput<Entity extends object> {
+    /** Entity class or stable entity name handled by the execution engine. */
+    readonly entity: TypedSheetsEntityReference<Entity>;
+    /** Overrides the execution engine's class name when a stable alias is needed. */
+    readonly entityName?: string;
+    /** Stable logical Sheets identifier shared by its physical projections. */
+    readonly logicalSheetId: string;
+    /** String primary-key property used as SQLite/canonical entity identity. */
+    readonly primaryKey: TypedSheetsEntityProperty<Entity>;
+    /** Required unique property used by the v1 business-key index. */
+    readonly businessKey: TypedSheetsEntityProperty<Entity>;
+    /** Schema version registered for every physical projection of this entity. */
+    readonly schemaVersion: number;
+    /** Canonical business fields exposed by this mapping. */
+    readonly fields: readonly TypedSheetsEntityFieldMappingInput<Entity>[];
+    /** One System_State projection and, optionally, one User_Input projection. */
+    readonly projections: readonly TypedSheetsEntityProjectionMappingInput[];
+    /** System-only marker projected when `em.remove()` tombstones an entity. */
+    readonly tombstoneFieldName?: string;
+    /** Builds a deterministic projection-local row anchor from canonical identity. */
+    readonly anchorForEntity?: (entityId: string) => string;
+}
+/** Validated mapping metadata for one canonical entity. */
+export interface TypedSheetsEntityFieldMapping extends TypedSheetsEntityFieldCodec {
+    readonly property: string;
+    readonly fieldName: string;
+    readonly cellKind: NormalizedCellKind;
+    readonly ownership: FieldOwnership;
+    readonly required: boolean;
+    readonly unique: boolean;
+}
+/** Validated physical projection route. */
+export interface TypedSheetsEntityProjectionMapping {
+    readonly physicalSheetId: string;
+    readonly spreadsheetId: string;
+    readonly tabName: string;
+    readonly registeredRange: string;
+    readonly projection: TypedSheetsEntityProjection;
+}
+/** Adapter-neutral mapping consumed by the flush and observation bridges. */
+export interface TypedSheetsEntityMapping {
+    readonly entity: TypedSheetsEntityReference<object>;
+    readonly entityName: string;
+    readonly logicalSheetId: string;
+    readonly primaryKey: string;
+    readonly businessKey: TypedSheetsEntityFieldMapping;
+    readonly schemaVersion: number;
+    readonly fields: readonly TypedSheetsEntityFieldMapping[];
+    readonly projections: readonly TypedSheetsEntityProjectionMapping[];
+    readonly tombstoneFieldName: string;
+    readonly anchorForEntity: (entityId: string) => string;
+}
+/** An indexed collection of validated mappings used by one typed-sheets runtime. */
+export interface TypedSheetsEntityMappingRegistry {
+    readonly mappings: readonly TypedSheetsEntityMapping[];
+    findByEntityName(entityName: string): TypedSheetsEntityMapping | undefined;
+    findByLogicalSheetId(logicalSheetId: string): TypedSheetsEntityMapping | undefined;
+    findByPhysicalSheetId(physicalSheetId: string): TypedSheetsEntityMapping | undefined;
+}
+/** A physical projection plus its computed registry input and header schema. */
+export interface TypedSheetsMappedProjectionDefinition {
+    readonly mapping: TypedSheetsEntityMapping;
+    readonly projection: TypedSheetsEntityProjectionMapping;
+    readonly registration: RegisterSyncSheetInput;
+    readonly headers: readonly string[];
+}
+//# sourceMappingURL=contracts.d.ts.map

package/dist/application/orm/mapping/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../../../src/application/orm/mapping/contracts.ts"],"names":[],"mappings":"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"}

package/dist/application/orm/mapping/contracts.js

@@ -0,0 +1,8 @@
+/**
+ * Type contracts for entity-to-Sheets mappings.
+ *
+ * This file contains declarations only. Validation, indexing, projection
+ * registration, and value conversion live in their respective modules.
+ */
+export {};
+//# sourceMappingURL=contracts.js.map

package/dist/application/orm/mapping/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../../../src/application/orm/mapping/contracts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/application/orm/mapping/definition.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Validates and normalizes user-facing entity mapping declarations.
+ *
+ * This module is the construction boundary: callers provide flexible input,
+ * and every downstream mapping module receives a validated contract.
+ */
+import type { TypedSheetsEntityMapping, TypedSheetsEntityMappingInput } from "./contracts.js";
+/**
+ * Validates and normalizes a single entity-to-Sheets mapping declaration.
+ *
+ * It rejects ambiguous entity names, duplicated field names, missing business
+ * key guarantees, and a projection layout that would violate the v1
+ * User_Input/System_State ownership boundary.
+ */
+export declare function defineTypedSheetsEntityMapping<Entity extends object>(input: TypedSheetsEntityMappingInput<Entity>): TypedSheetsEntityMapping;
+//# sourceMappingURL=definition.d.ts.map

package/dist/application/orm/mapping/definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../../../src/application/orm/mapping/definition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,OAAO,KAAK,EAGV,wBAAwB,EACxB,6BAA6B,EAG9B,MAAM,gBAAgB,CAAC;AAMxB;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,SAAS,MAAM,EAClE,KAAK,EAAE,6BAA6B,CAAC,MAAM,CAAC,GAC3C,wBAAwB,CAkE1B"}

package/dist/application/orm/mapping/definition.js

@@ -0,0 +1,145 @@
+/**
+ * Validates and normalizes user-facing entity mapping declarations.
+ *
+ * This module is the construction boundary: callers provide flexible input,
+ * and every downstream mapping module receives a validated contract.
+ */
+import { EMPTY_STRING_LENGTH_ZERO, FIELD_OWNERSHIPS, } from "../../../domain/index.js";
+import { NORMALIZED_CELL_KINDS, } from "../../../shared/encoding/constants.js";
+import { SYNC_GATEWAY_PROJECTIONS } from "../../sync/gateway/constants.js";
+import { TYPED_SHEETS_ORM_ERROR_CODES, TypedSheetsOrmError, } from "../errors.js";
+/**
+ * Validates and normalizes a single entity-to-Sheets mapping declaration.
+ *
+ * It rejects ambiguous entity names, duplicated field names, missing business
+ * key guarantees, and a projection layout that would violate the v1
+ * User_Input/System_State ownership boundary.
+ */
+export function defineTypedSheetsEntityMapping(input) {
+    const entityName = input.entityName ?? entityReferenceName(input.entity);
+    requireText(entityName, "entity name");
+    requireText(input.logicalSheetId, "logical sheet ID");
+    requireText(input.primaryKey, "primary-key property");
+    requireText(input.businessKey, "business-key property");
+    if (!Number.isSafeInteger(input.schemaVersion) || input.schemaVersion < 1) {
+        throwInvalidMapping("schema version must be a positive safe integer");
+    }
+    if (input.fields.length === 0) {
+        throwInvalidMapping("an entity mapping must declare at least one field");
+    }
+    const fields = input.fields.map((field) => normalizeFieldMapping(field));
+    assertDistinct(fields.map((field) => field.property), "entity property");
+    assertDistinct(fields.map((field) => field.fieldName), "canonical field name");
+    const businessKey = fields.find((field) => field.property === input.businessKey);
+    if (businessKey === undefined) {
+        throwInvalidMapping("the business-key property must be declared as a mapped field");
+    }
+    if (!businessKey.required || !businessKey.unique) {
+        throwInvalidMapping("the business-key field must be required and unique");
+    }
+    if (fields.some((field) => field.unique && field.property !== input.businessKey)) {
+        throwInvalidMapping("v1 supports exactly one unique business-key field");
+    }
+    const projections = input.projections.map(normalizeProjectionMapping);
+    if (projections.length === 0) {
+        throwInvalidMapping("an entity mapping must declare a system_state projection");
+    }
+    assertDistinct(projections.map((projection) => projection.physicalSheetId), "physical sheet ID");
+    assertDistinct(projections.map((projection) => projection.projection), "projection kind");
+    if (!projections.some((projection) => projection.projection === SYNC_GATEWAY_PROJECTIONS.SYSTEM_STATE)) {
+        throwInvalidMapping("an entity mapping must declare exactly one system_state projection");
+    }
+    const tombstoneFieldName = input.tombstoneFieldName ?? "__typed_sheets_deleted";
+    requireText(tombstoneFieldName, "tombstone field name");
+    if (fields.some((field) => field.fieldName === tombstoneFieldName)) {
+        throwInvalidMapping("the tombstone field name cannot duplicate a mapped field");
+    }
+    const userInput = projections.find((projection) => projection.projection === SYNC_GATEWAY_PROJECTIONS.USER_INPUT);
+    if (userInput !== undefined && fields.every((field) => field.ownership !== FIELD_OWNERSHIPS.USER)) {
+        throwInvalidMapping("a user_input projection requires at least one user-owned field");
+    }
+    if (userInput !== undefined && businessKey.ownership !== FIELD_OWNERSHIPS.USER) {
+        throwInvalidMapping("a user_input projection requires a user-owned business-key field");
+    }
+    return {
+        entity: input.entity,
+        entityName,
+        logicalSheetId: input.logicalSheetId,
+        primaryKey: input.primaryKey,
+        businessKey,
+        schemaVersion: input.schemaVersion,
+        fields,
+        projections,
+        tombstoneFieldName,
+        anchorForEntity: input.anchorForEntity ?? defaultAnchorForEntity,
+    };
+}
+function normalizeFieldMapping(field) {
+    const property = field.property;
+    const fieldName = field.fieldName ?? property;
+    requireText(property, "entity property");
+    requireText(fieldName, "canonical field name");
+    if (!isNormalizedCellKind(field.cellKind)) {
+        throwInvalidMapping(`${fieldName} has an unsupported normalized cell kind`);
+    }
+    if (field.ownership !== FIELD_OWNERSHIPS.USER && field.ownership !== FIELD_OWNERSHIPS.SYSTEM) {
+        throwInvalidMapping(`${fieldName} has an unsupported ownership`);
+    }
+    return {
+        property,
+        fieldName,
+        cellKind: field.cellKind,
+        ownership: field.ownership,
+        required: field.required ?? false,
+        unique: field.unique ?? false,
+        ...(field.encode === undefined ? {} : { encode: field.encode }),
+        ...(field.decode === undefined ? {} : { decode: field.decode }),
+    };
+}
+function normalizeProjectionMapping(projection) {
+    requireText(projection.physicalSheetId, "physical sheet ID");
+    requireText(projection.spreadsheetId, "spreadsheet ID");
+    requireText(projection.tabName, "tab name");
+    requireText(projection.registeredRange, "registered range");
+    if (projection.projection !== SYNC_GATEWAY_PROJECTIONS.USER_INPUT &&
+        projection.projection !== SYNC_GATEWAY_PROJECTIONS.SYSTEM_STATE) {
+        throwInvalidMapping("an entity mapping supports only user_input and system_state projections");
+    }
+    return { ...projection };
+}
+function entityReferenceName(entity) {
+    if (typeof entity === "string")
+        return entity;
+    const name = entity.name;
+    if (typeof name !== "string") {
+        throwInvalidMapping("an entity class must expose a stable name or entityName must be provided");
+    }
+    return name;
+}
+function assertDistinct(values, label) {
+    const seen = new Set();
+    for (const value of values) {
+        if (seen.has(value)) {
+            throwInvalidMapping(`a mapping cannot repeat ${label}: ${value}`);
+        }
+        seen.add(value);
+    }
+}
+function defaultAnchorForEntity(entityId) {
+    return `entity:${entityId}`;
+}
+function isNormalizedCellKind(value) {
+    return value === NORMALIZED_CELL_KINDS.STRING ||
+        value === NORMALIZED_CELL_KINDS.NUMBER ||
+        value === NORMALIZED_CELL_KINDS.BOOLEAN ||
+        value === NORMALIZED_CELL_KINDS.DATE;
+}
+function requireText(value, label) {
+    if (value.length === EMPTY_STRING_LENGTH_ZERO) {
+        throwInvalidMapping(`${label} is required`);
+    }
+}
+function throwInvalidMapping(message) {
+    throw new TypedSheetsOrmError(TYPED_SHEETS_ORM_ERROR_CODES.INVALID_ENTITY_MAPPING, message);
+}
+//# sourceMappingURL=definition.js.map

package/dist/application/orm/mapping/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../../../src/application/orm/mapping/definition.ts"],"names":[],"mappings":"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"}

package/dist/application/orm/mapping/entityMapping.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Public mapping entrypoint.
+ *
+ * Implementation is split by responsibility; this barrel preserves the
+ * existing import path for callers while keeping the individual modules small.
+ */
+export * from "./contracts.js";
+export * from "./definition.js";
+export * from "./identity.js";
+export * from "./projection.js";
+export * from "./registry.js";
+export * from "./values.js";
+//# sourceMappingURL=entityMapping.d.ts.map

package/dist/application/orm/mapping/entityMapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entityMapping.d.ts","sourceRoot":"","sources":["../../../../src/application/orm/mapping/entityMapping.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC"}

package/dist/application/orm/mapping/entityMapping.js

@@ -0,0 +1,13 @@
+/**
+ * Public mapping entrypoint.
+ *
+ * Implementation is split by responsibility; this barrel preserves the
+ * existing import path for callers while keeping the individual modules small.
+ */
+export * from "./contracts.js";
+export * from "./definition.js";
+export * from "./identity.js";
+export * from "./projection.js";
+export * from "./registry.js";
+export * from "./values.js";
+//# sourceMappingURL=entityMapping.js.map

package/dist/application/orm/mapping/entityMapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entityMapping.js","sourceRoot":"","sources":["../../../../src/application/orm/mapping/entityMapping.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC"}