@entifix/core 0.1.0-0

package/dist/entity-definition/helpers/entity-definition-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/entity-definition/helpers/entity-definition-helpers.ts"],"sourcesContent":["(Symbol as { metadata?: symbol }).metadata ??= Symbol.for('Symbol.metadata');\n\nimport { EntifixBuildError } from '../../base-entities/entifix-error/index.js';\nimport { Entity, EntityConstructor } from '../../types/Entity.js';\nimport { UseCaseConstructor } from '../../types/UseCase.js';\nimport {\n  type ChildConstructor,\n  MetaAccessor,\n} from '../meta-entities/meta-accessor/index.js';\nimport { MetaEntity } from '../meta-entities/meta-entity/index.js';\nimport { MetaMethod } from '../meta-entities/meta-method/index.js';\nimport {\n  MetaUseCase,\n  MetaUseCaseBinding,\n} from '../meta-entities/meta-use-case/index.js';\n\ndeclare global {\n  interface SymbolConstructor {\n    readonly metadata: unique symbol;\n  }\n}\n\nexport const META_ENTITY_KEY = Symbol('MetaEntity');\nexport const META_ACCESSOR_KEY = Symbol('MetaAccessor');\nexport const META_METHOD_KEY = Symbol('MetaMethod');\nexport const META_USE_CASE_KEY = Symbol('MetaUseCase');\nexport const META_USE_CASE_BINDING_KEY = Symbol('MetaUseCaseBinding');\n\nfunction requireMetadata(\n  metadata: DecoratorMetadataObject | undefined,\n): DecoratorMetadataObject {\n  if (!metadata) {\n    throw new EntifixBuildError(\n      'Decorator metadata unavailable — Symbol.metadata polyfill missing or stage-3 decorator emit not enabled.',\n    );\n  }\n  return metadata;\n}\n\nexport function setMetaEntity(\n  metadata: DecoratorMetadataObject | undefined,\n  metaEntity: MetaEntity,\n) {\n  requireMetadata(metadata)[META_ENTITY_KEY] = metaEntity;\n}\n\nexport function appendMetaAccessor(\n  metadata: DecoratorMetadataObject | undefined,\n  metaAccessor: MetaAccessor,\n) {\n  const meta = requireMetadata(metadata);\n  const existing =\n    (meta[META_ACCESSOR_KEY] as MetaAccessor[] | undefined) ?? [];\n  meta[META_ACCESSOR_KEY] = [...existing, metaAccessor];\n}\n\nexport function appendMetaMethod(\n  metadata: DecoratorMetadataObject | undefined,\n  metaMethod: MetaMethod,\n) {\n  const meta = requireMetadata(metadata);\n  const existing = (meta[META_METHOD_KEY] as MetaMethod[] | undefined) ?? [];\n  meta[META_METHOD_KEY] = [...existing, metaMethod];\n}\n\n/**\n * Append a use case to the metadata of the entity it acts on.\n *\n * This is the one decorator that writes a bag other than its own: a use case is\n * declared on its own class, but the entity is what a surface holds, so the\n * descriptor has to end up there. The consequence is that a use-case module\n * which is never imported leaves the entity looking as if it had no actions,\n * which is why `@r10c/slices` asserts every `@useCase()` class is re-exported\n * from its package barrel.\n *\n * It reads the target's **own** metadata rather than going through\n * {@link readMetadata}. `Symbol.metadata` resolves along the prototype chain, so\n * an inherited read would append the verb to a base class's bag and leak it to\n * every subclass. A target with no own metadata is an entity missing\n * `@entity()`, or a circular import that evaluated the use case first.\n */\nexport function appendMetaUseCase<TEntity extends Entity>(\n  target: EntityConstructor<TEntity>,\n  metaUseCase: MetaUseCase,\n) {\n  const own = Object.getOwnPropertyDescriptor(target, Symbol.metadata)\n    ?.value as DecoratorMetadataObject | null | undefined;\n  if (!own) {\n    throw new EntifixBuildError(\n      `Use case \"${metaUseCase.key}\" targets ${target.name}, which has no metadata of its own — it is missing @entity(), or a circular import evaluated the use case first.`,\n    );\n  }\n  const existing = (own[META_USE_CASE_KEY] as MetaUseCase[] | undefined) ?? [];\n  own[META_USE_CASE_KEY] = [...existing, metaUseCase];\n}\n\n/**\n * Record on the use-case class itself which entity and verb it implements, so\n * the permission can be derived from the class alone. That is what keeps the\n * verb string written once, at the declaration, instead of being retyped at\n * every guard.\n */\nexport function setMetaUseCaseBinding(\n  metadata: DecoratorMetadataObject | undefined,\n  binding: MetaUseCaseBinding,\n) {\n  requireMetadata(metadata)[META_USE_CASE_BINDING_KEY] = binding;\n}\n\nfunction readMetadata(\n  target: ChildConstructor,\n): DecoratorMetadataObject | undefined {\n  return target[Symbol.metadata] ?? undefined;\n}\n\nexport function extractMetaEntity<TEntity extends Entity>(\n  target: EntityConstructor<TEntity>,\n): MetaEntity {\n  const metadata = readMetadata(target);\n  const metaEntity = metadata?.[META_ENTITY_KEY] as MetaEntity | undefined;\n  if (!metaEntity) {\n    throw new EntifixBuildError(`MetaEntity not found for ${target.name}`);\n  }\n  return metaEntity;\n}\n\n/**\n * Every accessor declared on a class.\n *\n * The target is a {@link ChildConstructor}, not an `EntityConstructor`: an\n * `@accessor()` writes to its own class's metadata bag with no help from\n * `@entity()`, so a `composition` member's child — a value with no `id` — is\n * described by exactly this walk.\n */\nexport function extractMetaAccessors(target: ChildConstructor): MetaAccessor[] {\n  const metadata = readMetadata(target);\n  return (metadata?.[META_ACCESSOR_KEY] as MetaAccessor[] | undefined) ?? [];\n}\n\nexport function extractMetaMethods<TEntity extends Entity>(\n  target: EntityConstructor<TEntity>,\n): MetaMethod[] {\n  const metadata = readMetadata(target);\n  return (metadata?.[META_METHOD_KEY] as MetaMethod[] | undefined) ?? [];\n}\n\n/** Every use case declared against an entity. Empty until one is imported. */\nexport function extractMetaUseCases<TEntity extends Entity>(\n  target: EntityConstructor<TEntity>,\n): MetaUseCase[] {\n  const metadata = readMetadata(target);\n  return (metadata?.[META_USE_CASE_KEY] as MetaUseCase[] | undefined) ?? [];\n}\n\n/** The entity and verb a `@useCase()` class implements. */\nexport function extractMetaUseCaseBinding(\n  target: UseCaseConstructor,\n): MetaUseCaseBinding {\n  const metadata = (\n    target as { [Symbol.metadata]?: DecoratorMetadataObject | null }\n  )[Symbol.metadata];\n  const binding = metadata?.[META_USE_CASE_BINDING_KEY] as\n    MetaUseCaseBinding | undefined;\n  if (!binding) {\n    throw new EntifixBuildError(\n      `MetaUseCase not found for ${target.name} — is it missing @useCase()?`,\n    );\n  }\n  return binding;\n}\n"],"names":["Symbol","metadata","for","EntifixBuildError","META_ENTITY_KEY","META_ACCESSOR_KEY","META_METHOD_KEY","META_USE_CASE_KEY","META_USE_CASE_BINDING_KEY","requireMetadata","setMetaEntity","metaEntity","appendMetaAccessor","metaAccessor","meta","existing","appendMetaMethod","metaMethod","appendMetaUseCase","target","metaUseCase","own","Object","getOwnPropertyDescriptor","value","key","name","setMetaUseCaseBinding","binding","readMetadata","undefined","extractMetaEntity","extractMetaAccessors","extractMetaMethods","extractMetaUseCases","extractMetaUseCaseBinding"],"mappings":"IAACA,SAAD;CAAA,YAAA,CAACA,UAAAA,QAAiCC,QAAQ,YAA1C,YAAA,AAACD,QAAiCC,QAAQ,GAAKD,OAAOE,GAAG,CAAC;AAE1D,SAASC,iBAAiB,QAAQ,6CAA6C;AAoB/E,OAAO,MAAMC,kBAAkBJ,OAAO,cAAc;AACpD,OAAO,MAAMK,oBAAoBL,OAAO,gBAAgB;AACxD,OAAO,MAAMM,kBAAkBN,OAAO,cAAc;AACpD,OAAO,MAAMO,oBAAoBP,OAAO,eAAe;AACvD,OAAO,MAAMQ,4BAA4BR,OAAO,sBAAsB;AAEtE,SAASS,gBACPR,QAA6C;IAE7C,IAAI,CAACA,UAAU;QACb,MAAM,IAAIE,kBACR;IAEJ;IACA,OAAOF;AACT;AAEA,OAAO,SAASS,cACdT,QAA6C,EAC7CU,UAAsB;IAEtBF,gBAAgBR,SAAS,CAACG,gBAAgB,GAAGO;AAC/C;AAEA,OAAO,SAASC,mBACdX,QAA6C,EAC7CY,YAA0B;QAIvBC;IAFH,MAAMA,OAAOL,gBAAgBR;IAC7B,MAAMc,YACHD,0BAAAA,IAAI,CAACT,kBAAkB,YAAvBS,0BAA0D,EAAE;IAC/DA,IAAI,CAACT,kBAAkB,GAAG;WAAIU;QAAUF;KAAa;AACvD;AAEA,OAAO,SAASG,iBACdf,QAA6C,EAC7CgB,UAAsB;QAGJH;IADlB,MAAMA,OAAOL,gBAAgBR;IAC7B,MAAMc,YAAYD,wBAAAA,IAAI,CAACR,gBAAgB,YAArBQ,wBAAsD,EAAE;IAC1EA,IAAI,CAACR,gBAAgB,GAAG;WAAIS;QAAUE;KAAW;AACnD;AAEA;;;;;;;;;;;;;;;CAeC,GACD,OAAO,SAASC,kBACdC,MAAkC,EAClCC,WAAwB;QASNC;QAPNC;IAAZ,MAAMD,OAAMC,mCAAAA,OAAOC,wBAAwB,CAACJ,QAAQnB,OAAOC,QAAQ,sBAAvDqB,iCACRE,KAAK;IACT,IAAI,CAACH,KAAK;QACR,MAAM,IAAIlB,kBACR,CAAC,UAAU,EAAEiB,YAAYK,GAAG,CAAC,UAAU,EAAEN,OAAOO,IAAI,CAAC,gHAAgH,CAAC;IAE1K;IACA,MAAMX,YAAYM,yBAAAA,GAAG,CAACd,kBAAkB,YAAtBc,yBAAwD,EAAE;IAC5EA,GAAG,CAACd,kBAAkB,GAAG;WAAIQ;QAAUK;KAAY;AACrD;AAEA;;;;;CAKC,GACD,OAAO,SAASO,sBACd1B,QAA6C,EAC7C2B,OAA2B;IAE3BnB,gBAAgBR,SAAS,CAACO,0BAA0B,GAAGoB;AACzD;AAEA,SAASC,aACPV,MAAwB;QAEjBA;IAAP,QAAOA,0BAAAA,MAAM,CAACnB,OAAOC,QAAQ,CAAC,YAAvBkB,0BAA2BW;AACpC;AAEA,OAAO,SAASC,kBACdZ,MAAkC;IAElC,MAAMlB,WAAW4B,aAAaV;IAC9B,MAAMR,aAAaV,4BAAAA,QAAU,CAACG,gBAAgB;IAC9C,IAAI,CAACO,YAAY;QACf,MAAM,IAAIR,kBAAkB,CAAC,yBAAyB,EAAEgB,OAAOO,IAAI,EAAE;IACvE;IACA,OAAOf;AACT;AAEA;;;;;;;CAOC,GACD,OAAO,SAASqB,qBAAqBb,MAAwB;;IAC3D,MAAMlB,WAAW4B,aAAaV;IAC9B,eAAQlB,4BAAAA,QAAU,CAACI,kBAAkB,mBAAmC,EAAE;AAC5E;AAEA,OAAO,SAAS4B,mBACdd,MAAkC;;IAElC,MAAMlB,WAAW4B,aAAaV;IAC9B,eAAQlB,4BAAAA,QAAU,CAACK,gBAAgB,mBAAiC,EAAE;AACxE;AAEA,4EAA4E,GAC5E,OAAO,SAAS4B,oBACdf,MAAkC;;IAElC,MAAMlB,WAAW4B,aAAaV;IAC9B,eAAQlB,4BAAAA,QAAU,CAACM,kBAAkB,mBAAkC,EAAE;AAC3E;AAEA,yDAAyD,GACzD,OAAO,SAAS4B,0BACdhB,MAA0B;IAE1B,MAAMlB,WAAW,AACfkB,MACD,CAACnB,OAAOC,QAAQ,CAAC;IAClB,MAAM2B,UAAU3B,4BAAAA,QAAU,CAACO,0BAA0B;IAErD,IAAI,CAACoB,SAAS;QACZ,MAAM,IAAIzB,kBACR,CAAC,0BAA0B,EAAEgB,OAAOO,IAAI,CAAC,4BAA4B,CAAC;IAE1E;IACA,OAAOE;AACT"}

package/dist/entity-definition/helpers/index.d.ts

@@ -0,0 +1,2 @@
+export * from './entity-definition-helpers.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/entity-definition/helpers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/entity-definition/helpers/index.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAC"}

package/dist/entity-definition/helpers/index.js

@@ -0,0 +1,3 @@
+export * from './entity-definition-helpers.js';
+
+//# sourceMappingURL=index.js.map

package/dist/entity-definition/helpers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/entity-definition/helpers/index.ts"],"sourcesContent":["export * from './entity-definition-helpers.js';\n"],"names":[],"mappings":"AAAA,cAAc,iCAAiC"}

package/dist/entity-definition/links/apply-entity-links/apply-entity-links.d.ts

@@ -0,0 +1,48 @@
+import { Entity } from '../../../types/Entity.js';
+import { EntityDraft } from '../../../types/EntityDraft.js';
+import { EntityFieldDescriptor } from '../../describe/index.js';
+/**
+ * The instances a user picked, keyed by accessor name — the sidecar to a form's
+ * string draft.
+ *
+ * A draft holds ids because it must stay JSON (a workspace autosaves it), but an
+ * id alone cannot be written as an embedded relation. So the picker remembers the
+ * instance it handed over, and this map is that memory.
+ *
+ * It is a *cache*, and it is not persisted — it dies with the page, and a
+ * restored draft arrives holding ids and nothing else. What refills it is
+ * `EntityLinkSource.selected.entity`, which resolves the id the draft did keep.
+ * For an `id` member a missing entry costs nothing; for an `embedded` one
+ * {@link applyEntityLinks} throws rather than write the wrong wire shape.
+ */
+export type EntityLinkSelection = Record<string, Entity | undefined>;
+/**
+ * Writes a draft's relations onto a freshly built entity, following each
+ * member's declared {@link EntityFieldDescriptor.linkSerialization}.
+ *
+ * This is the counterpart to `serializeEntity`, which inlines a link whenever it
+ * `isLoaded`: an `embedded` member therefore needs the picked instance handed to
+ * `setValue`, while an `id` member must be given only the scalar even when the
+ * instance is at hand — otherwise the wire shape would flip the moment a picker
+ * happened to hold the target.
+ *
+ * Pure and framework-free, so the same reconstruction runs in a browser form and
+ * in a backend use-case that assembles an entity from a raw draft.
+ *
+ * `linkCollection` members are left untouched: the to-many editor is a follow-up,
+ * and this is the branch where `setIds`/`setValues` will land.
+ *
+ * Throws {@link EntifixLogicError} when an `embedded` member holds an id with no
+ * instance to inline — see the branch below for why that is a fault and not a
+ * fallback.
+ */
+export declare function applyEntityLinks<TEntity extends Entity>(instance: TEntity, descriptors: readonly EntityFieldDescriptor[], values: EntityDraft, selection?: EntityLinkSelection): void;
+/**
+ * Seeds a {@link EntityLinkSelection} from a record whose relations already
+ * arrived materialized — an embedded payload, or a link a use-case resolved.
+ *
+ * It is what keeps opening a loaded record from re-fetching every relation label
+ * the record already carries.
+ */
+export declare function seedEntityLinkSelection<TEntity extends Entity>(descriptors: readonly EntityFieldDescriptor[], entity: TEntity | undefined): EntityLinkSelection;
+//# sourceMappingURL=apply-entity-links.d.ts.map

package/dist/entity-definition/links/apply-entity-links/apply-entity-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-entity-links.d.ts","sourceRoot":"","sources":["../../../../src/entity-definition/links/apply-entity-links/apply-entity-links.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAY,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAmB,MAAM,+BAA+B,CAAC;AAC7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAGhE;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAErE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,SAAS,MAAM,EACrD,QAAQ,EAAE,OAAO,EACjB,WAAW,EAAE,SAAS,qBAAqB,EAAE,EAC7C,MAAM,EAAE,WAAW,EACnB,SAAS,GAAE,mBAAwB,GAClC,IAAI,CAkDN;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,SAAS,MAAM,EAC5D,WAAW,EAAE,SAAS,qBAAqB,EAAE,EAC7C,MAAM,EAAE,OAAO,GAAG,SAAS,GAC1B,mBAAmB,CAgBrB"}

package/dist/entity-definition/links/apply-entity-links/apply-entity-links.js

@@ -0,0 +1,88 @@
+import { EntifixLogicError } from '../../../base-entities/entifix-error/index.js';
+import { readDraftString } from '../../../types/EntityDraft.js';
+import { EntityLink } from '../entity-link/index.js';
+/**
+ * Writes a draft's relations onto a freshly built entity, following each
+ * member's declared {@link EntityFieldDescriptor.linkSerialization}.
+ *
+ * This is the counterpart to `serializeEntity`, which inlines a link whenever it
+ * `isLoaded`: an `embedded` member therefore needs the picked instance handed to
+ * `setValue`, while an `id` member must be given only the scalar even when the
+ * instance is at hand — otherwise the wire shape would flip the moment a picker
+ * happened to hold the target.
+ *
+ * Pure and framework-free, so the same reconstruction runs in a browser form and
+ * in a backend use-case that assembles an entity from a raw draft.
+ *
+ * `linkCollection` members are left untouched: the to-many editor is a follow-up,
+ * and this is the branch where `setIds`/`setValues` will land.
+ *
+ * Throws {@link EntifixLogicError} when an `embedded` member holds an id with no
+ * instance to inline — see the branch below for why that is a fault and not a
+ * fallback.
+ */ export function applyEntityLinks(instance, descriptors, values, selection = {}) {
+    for (const descriptor of descriptors){
+        var _picked_id;
+        if (descriptor.type !== 'link') continue;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const link = instance[descriptor.name];
+        // A link accessor is expected to be pre-initialized by the constructor. A
+        // member typed `link` that is not one is a declaration mistake, not a value
+        // to coerce — skipping keeps this helper from writing nonsense onto it.
+        if (!(link instanceof EntityLink)) continue;
+        const picked = selection[descriptor.name];
+        // Read as a string rather than trusting the draft's `JsonValue`: a
+        // relation's draft value is a foreign key, and a member that came back
+        // from storage as anything else must read as absent rather than be cast
+        // onto the link as an id.
+        const rawId = readDraftString(values, descriptor.name);
+        if (picked === undefined) {
+            // An `embedded` member cannot be written from an id: `serializeEntity`
+            // inlines whatever `isLoaded`, so falling through here would emit the `id`
+            // shape onto a member the entity declares as inlined — silently, and
+            // differently from the same save a moment earlier when the picker still
+            // held the instance. The wire shape is metadata, not a function of what
+            // the UI happens to have in memory, so this is a fault rather than a
+            // degradation. The caller's job is to resolve the id first
+            // (`EntityLinkSource.selected.entity`) and hand the instance over.
+            if (descriptor.linkSerialization === 'embedded' && rawId !== '') {
+                throw new EntifixLogicError(`Cannot write "${descriptor.name}" as an embedded relation: the draft ` + 'holds an id but no instance. Resolve the id through the link ' + "source's `selected.entity` before submitting, or declare the " + "member `linkSerialization: 'id'`.", undefined, {
+                    member: descriptor.name,
+                    id: rawId
+                });
+            }
+            link.setValue(undefined);
+            link.setId(rawId === '' ? undefined : rawId);
+            continue;
+        }
+        if (descriptor.linkSerialization === 'embedded') {
+            link.setValue(picked);
+            continue;
+        }
+        link.setValue(undefined);
+        link.setId((_picked_id = picked.id) != null ? _picked_id : rawId === '' ? undefined : rawId);
+    }
+}
+/**
+ * Seeds a {@link EntityLinkSelection} from a record whose relations already
+ * arrived materialized — an embedded payload, or a link a use-case resolved.
+ *
+ * It is what keeps opening a loaded record from re-fetching every relation label
+ * the record already carries.
+ */ export function seedEntityLinkSelection(descriptors, entity) {
+    const selection = {};
+    if (entity == null) return selection;
+    // Only to-one links, for the same reason {@link applyEntityLinks} writes only
+    // those: a collection's values are not a single selection.
+    for (const descriptor of descriptors){
+        if (descriptor.type !== 'link') continue;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const link = entity[descriptor.name];
+        if (link instanceof EntityLink && link.value !== undefined) {
+            selection[descriptor.name] = link.value;
+        }
+    }
+    return selection;
+}
+
+//# sourceMappingURL=apply-entity-links.js.map

package/dist/entity-definition/links/apply-entity-links/apply-entity-links.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/entity-definition/links/apply-entity-links/apply-entity-links.ts"],"sourcesContent":["import { EntifixLogicError } from '../../../base-entities/entifix-error/index.js';\nimport { Entity, EntityId } from '../../../types/Entity.js';\nimport { EntityDraft, readDraftString } from '../../../types/EntityDraft.js';\nimport { EntityFieldDescriptor } from '../../describe/index.js';\nimport { EntityLink } from '../entity-link/index.js';\n\n/**\n * The instances a user picked, keyed by accessor name — the sidecar to a form's\n * string draft.\n *\n * A draft holds ids because it must stay JSON (a workspace autosaves it), but an\n * id alone cannot be written as an embedded relation. So the picker remembers the\n * instance it handed over, and this map is that memory.\n *\n * It is a *cache*, and it is not persisted — it dies with the page, and a\n * restored draft arrives holding ids and nothing else. What refills it is\n * `EntityLinkSource.selected.entity`, which resolves the id the draft did keep.\n * For an `id` member a missing entry costs nothing; for an `embedded` one\n * {@link applyEntityLinks} throws rather than write the wrong wire shape.\n */\nexport type EntityLinkSelection = Record<string, Entity | undefined>;\n\n/**\n * Writes a draft's relations onto a freshly built entity, following each\n * member's declared {@link EntityFieldDescriptor.linkSerialization}.\n *\n * This is the counterpart to `serializeEntity`, which inlines a link whenever it\n * `isLoaded`: an `embedded` member therefore needs the picked instance handed to\n * `setValue`, while an `id` member must be given only the scalar even when the\n * instance is at hand — otherwise the wire shape would flip the moment a picker\n * happened to hold the target.\n *\n * Pure and framework-free, so the same reconstruction runs in a browser form and\n * in a backend use-case that assembles an entity from a raw draft.\n *\n * `linkCollection` members are left untouched: the to-many editor is a follow-up,\n * and this is the branch where `setIds`/`setValues` will land.\n *\n * Throws {@link EntifixLogicError} when an `embedded` member holds an id with no\n * instance to inline — see the branch below for why that is a fault and not a\n * fallback.\n */\nexport function applyEntityLinks<TEntity extends Entity>(\n  instance: TEntity,\n  descriptors: readonly EntityFieldDescriptor[],\n  values: EntityDraft,\n  selection: EntityLinkSelection = {},\n): void {\n  for (const descriptor of descriptors) {\n    if (descriptor.type !== 'link') continue;\n\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    const link = (instance as any)[descriptor.name];\n    // A link accessor is expected to be pre-initialized by the constructor. A\n    // member typed `link` that is not one is a declaration mistake, not a value\n    // to coerce — skipping keeps this helper from writing nonsense onto it.\n    if (!(link instanceof EntityLink)) continue;\n\n    const picked = selection[descriptor.name];\n    // Read as a string rather than trusting the draft's `JsonValue`: a\n    // relation's draft value is a foreign key, and a member that came back\n    // from storage as anything else must read as absent rather than be cast\n    // onto the link as an id.\n    const rawId = readDraftString(values, descriptor.name);\n\n    if (picked === undefined) {\n      // An `embedded` member cannot be written from an id: `serializeEntity`\n      // inlines whatever `isLoaded`, so falling through here would emit the `id`\n      // shape onto a member the entity declares as inlined — silently, and\n      // differently from the same save a moment earlier when the picker still\n      // held the instance. The wire shape is metadata, not a function of what\n      // the UI happens to have in memory, so this is a fault rather than a\n      // degradation. The caller's job is to resolve the id first\n      // (`EntityLinkSource.selected.entity`) and hand the instance over.\n      if (descriptor.linkSerialization === 'embedded' && rawId !== '') {\n        throw new EntifixLogicError(\n          `Cannot write \"${descriptor.name}\" as an embedded relation: the draft ` +\n            'holds an id but no instance. Resolve the id through the link ' +\n            \"source's `selected.entity` before submitting, or declare the \" +\n            \"member `linkSerialization: 'id'`.\",\n          undefined,\n          { member: descriptor.name, id: rawId },\n        );\n      }\n      link.setValue(undefined);\n      link.setId(rawId === '' ? undefined : (rawId as EntityId));\n      continue;\n    }\n\n    if (descriptor.linkSerialization === 'embedded') {\n      link.setValue(picked);\n      continue;\n    }\n\n    link.setValue(undefined);\n    link.setId(picked.id ?? (rawId === '' ? undefined : (rawId as EntityId)));\n  }\n}\n\n/**\n * Seeds a {@link EntityLinkSelection} from a record whose relations already\n * arrived materialized — an embedded payload, or a link a use-case resolved.\n *\n * It is what keeps opening a loaded record from re-fetching every relation label\n * the record already carries.\n */\nexport function seedEntityLinkSelection<TEntity extends Entity>(\n  descriptors: readonly EntityFieldDescriptor[],\n  entity: TEntity | undefined,\n): EntityLinkSelection {\n  const selection: EntityLinkSelection = {};\n  if (entity == null) return selection;\n\n  // Only to-one links, for the same reason {@link applyEntityLinks} writes only\n  // those: a collection's values are not a single selection.\n  for (const descriptor of descriptors) {\n    if (descriptor.type !== 'link') continue;\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    const link = (entity as any)[descriptor.name];\n    if (link instanceof EntityLink && link.value !== undefined) {\n      selection[descriptor.name] = link.value;\n    }\n  }\n\n  return selection;\n}\n"],"names":["EntifixLogicError","readDraftString","EntityLink","applyEntityLinks","instance","descriptors","values","selection","descriptor","picked","type","link","name","rawId","undefined","linkSerialization","member","id","setValue","setId","seedEntityLinkSelection","entity","value"],"mappings":"AAAA,SAASA,iBAAiB,QAAQ,gDAAgD;AAElF,SAAsBC,eAAe,QAAQ,gCAAgC;AAE7E,SAASC,UAAU,QAAQ,0BAA0B;AAkBrD;;;;;;;;;;;;;;;;;;;CAmBC,GACD,OAAO,SAASC,iBACdC,QAAiB,EACjBC,WAA6C,EAC7CC,MAAmB,EACnBC,YAAiC,CAAC,CAAC;IAEnC,KAAK,MAAMC,cAAcH,YAAa;YA+CzBI;QA9CX,IAAID,WAAWE,IAAI,KAAK,QAAQ;QAEhC,8DAA8D;QAC9D,MAAMC,OAAO,AAACP,QAAgB,CAACI,WAAWI,IAAI,CAAC;QAC/C,0EAA0E;QAC1E,4EAA4E;QAC5E,wEAAwE;QACxE,IAAI,CAAED,CAAAA,gBAAgBT,UAAS,GAAI;QAEnC,MAAMO,SAASF,SAAS,CAACC,WAAWI,IAAI,CAAC;QACzC,mEAAmE;QACnE,uEAAuE;QACvE,wEAAwE;QACxE,0BAA0B;QAC1B,MAAMC,QAAQZ,gBAAgBK,QAAQE,WAAWI,IAAI;QAErD,IAAIH,WAAWK,WAAW;YACxB,uEAAuE;YACvE,2EAA2E;YAC3E,qEAAqE;YACrE,wEAAwE;YACxE,wEAAwE;YACxE,qEAAqE;YACrE,2DAA2D;YAC3D,mEAAmE;YACnE,IAAIN,WAAWO,iBAAiB,KAAK,cAAcF,UAAU,IAAI;gBAC/D,MAAM,IAAIb,kBACR,CAAC,cAAc,EAAEQ,WAAWI,IAAI,CAAC,qCAAqC,CAAC,GACrE,kEACA,kEACA,qCACFE,WACA;oBAAEE,QAAQR,WAAWI,IAAI;oBAAEK,IAAIJ;gBAAM;YAEzC;YACAF,KAAKO,QAAQ,CAACJ;YACdH,KAAKQ,KAAK,CAACN,UAAU,KAAKC,YAAaD;YACvC;QACF;QAEA,IAAIL,WAAWO,iBAAiB,KAAK,YAAY;YAC/CJ,KAAKO,QAAQ,CAACT;YACd;QACF;QAEAE,KAAKO,QAAQ,CAACJ;QACdH,KAAKQ,KAAK,EAACV,aAAAA,OAAOQ,EAAE,YAATR,aAAcI,UAAU,KAAKC,YAAaD;IACvD;AACF;AAEA;;;;;;CAMC,GACD,OAAO,SAASO,wBACdf,WAA6C,EAC7CgB,MAA2B;IAE3B,MAAMd,YAAiC,CAAC;IACxC,IAAIc,UAAU,MAAM,OAAOd;IAE3B,8EAA8E;IAC9E,2DAA2D;IAC3D,KAAK,MAAMC,cAAcH,YAAa;QACpC,IAAIG,WAAWE,IAAI,KAAK,QAAQ;QAChC,8DAA8D;QAC9D,MAAMC,OAAO,AAACU,MAAc,CAACb,WAAWI,IAAI,CAAC;QAC7C,IAAID,gBAAgBT,cAAcS,KAAKW,KAAK,KAAKR,WAAW;YAC1DP,SAAS,CAACC,WAAWI,IAAI,CAAC,GAAGD,KAAKW,KAAK;QACzC;IACF;IAEA,OAAOf;AACT"}

package/dist/entity-definition/links/apply-entity-links/index.d.ts

@@ -0,0 +1,2 @@
+export * from './apply-entity-links.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/entity-definition/links/apply-entity-links/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/entity-definition/links/apply-entity-links/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC"}

package/dist/entity-definition/links/apply-entity-links/index.js

@@ -0,0 +1,3 @@
+export * from './apply-entity-links.js';
+
+//# sourceMappingURL=index.js.map

package/dist/entity-definition/links/apply-entity-links/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/entity-definition/links/apply-entity-links/index.ts"],"sourcesContent":["export * from './apply-entity-links.js';\n"],"names":[],"mappings":"AAAA,cAAc,0BAA0B"}

package/dist/entity-definition/links/entity-collection-link/entity-collection-link.d.ts

@@ -0,0 +1,29 @@
+import { Effect } from 'effect';
+import { EntifixError } from '../../../base-entities/entifix-error/index.js';
+import { Entity, EntityConstructor, EntityId } from '../../../types/Entity.js';
+import { EntityLinkResolver } from '../entity-link/index.js';
+export interface EntityCollectionLinkInit<TEntity extends Entity> {
+    ids?: EntityId[];
+    values?: TEntity[];
+}
+/**
+ * A one-to-many reference. Like {@link EntityLink} it accepts either foreign
+ * keys (lazy, resolved through an {@link EntityLinkResolver}) or embedded
+ * instances, but for a collection of targets.
+ */
+export declare class EntityCollectionLink<TEntity extends Entity> {
+    #private;
+    readonly entityConstructor: EntityConstructor<TEntity>;
+    constructor(entityConstructor: EntityConstructor<TEntity>, init?: EntityCollectionLinkInit<TEntity>);
+    setIds(ids: EntityId[]): void;
+    setValues(values: TEntity[] | undefined): void;
+    /**
+     * Fetches every referenced target through the resolver and caches the result.
+     */
+    reload(resolver: EntityLinkResolver): Effect.Effect<TEntity[], EntifixError>;
+    resolve(resolver: EntityLinkResolver): Effect.Effect<TEntity[], EntifixError>;
+    get ids(): EntityId[];
+    get values(): TEntity[] | undefined;
+    get isLoaded(): boolean;
+}
+//# sourceMappingURL=entity-collection-link.d.ts.map

package/dist/entity-definition/links/entity-collection-link/entity-collection-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-collection-link.d.ts","sourceRoot":"","sources":["../../../../src/entity-definition/links/entity-collection-link/entity-collection-link.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,OAAO,EAAE,YAAY,EAAE,MAAM,+CAA+C,CAAC;AAC7E,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,MAAM,WAAW,wBAAwB,CAAC,OAAO,SAAS,MAAM;IAC9D,GAAG,CAAC,EAAE,QAAQ,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,qBAAa,oBAAoB,CAAC,OAAO,SAAS,MAAM;;IAEtD,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;gBAOrD,iBAAiB,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAC7C,IAAI,CAAC,EAAE,wBAAwB,CAAC,OAAO,CAAC;IAc1C,MAAM,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,IAAI;IAI7B,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,SAAS,GAAG,IAAI;IAS9C;;OAEG;IACH,MAAM,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,YAAY,CAAC;IAQ5E,OAAO,CACL,QAAQ,EAAE,kBAAkB,GAC3B,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,YAAY,CAAC;IAQzC,IAAI,GAAG,IAAI,QAAQ,EAAE,CAEpB;IAED,IAAI,MAAM,IAAI,OAAO,EAAE,GAAG,SAAS,CAElC;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;CAEF"}

package/dist/entity-definition/links/entity-collection-link/entity-collection-link.js

@@ -0,0 +1,61 @@
+import { _ as _class_private_field_loose_base } from "@swc/helpers/_/_class_private_field_loose_base";
+import { _ as _class_private_field_loose_key } from "@swc/helpers/_/_class_private_field_loose_key";
+import { Effect } from 'effect';
+var _ids = /*#__PURE__*/ _class_private_field_loose_key("_ids"), _values = /*#__PURE__*/ _class_private_field_loose_key("_values");
+/**
+ * A one-to-many reference. Like {@link EntityLink} it accepts either foreign
+ * keys (lazy, resolved through an {@link EntityLinkResolver}) or embedded
+ * instances, but for a collection of targets.
+ */ export class EntityCollectionLink {
+    // #endregion
+    // #region methods
+    setIds(ids) {
+        _class_private_field_loose_base(this, _ids)[_ids] = ids;
+    }
+    setValues(values) {
+        _class_private_field_loose_base(this, _values)[_values] = values;
+        if (values !== undefined) {
+            _class_private_field_loose_base(this, _ids)[_ids] = values.map((value)=>value.id).filter((id)=>id != null);
+        }
+    }
+    /**
+   * Fetches every referenced target through the resolver and caches the result.
+   */ reload(resolver) {
+        return Effect.forEach(_class_private_field_loose_base(this, _ids)[_ids], (id)=>resolver.resolve(this.entityConstructor, id), {
+            concurrency: 'unbounded'
+        }).pipe(Effect.tap((values)=>Effect.sync(()=>this.setValues(values))));
+    }
+    resolve(resolver) {
+        return _class_private_field_loose_base(this, _values)[_values] !== undefined ? Effect.succeed(_class_private_field_loose_base(this, _values)[_values]) : this.reload(resolver);
+    }
+    // #endregion
+    // #region accessors
+    get ids() {
+        return _class_private_field_loose_base(this, _ids)[_ids];
+    }
+    get values() {
+        return _class_private_field_loose_base(this, _values)[_values];
+    }
+    get isLoaded() {
+        return _class_private_field_loose_base(this, _values)[_values] !== undefined;
+    }
+    // #endregion
+    // #region constructors
+    constructor(entityConstructor, init){
+        var _ref, _ref1;
+        var _init_values;
+        Object.defineProperty(this, _ids, {
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, _values, {
+            writable: true,
+            value: void 0
+        });
+        this.entityConstructor = entityConstructor;
+        _class_private_field_loose_base(this, _values)[_values] = init == null ? void 0 : init.values;
+        _class_private_field_loose_base(this, _ids)[_ids] = (_ref = (_ref1 = init == null ? void 0 : init.ids) != null ? _ref1 : init == null ? void 0 : (_init_values = init.values) == null ? void 0 : _init_values.map((value)=>value.id).filter((id)=>id != null)) != null ? _ref : [];
+    }
+}
+
+//# sourceMappingURL=entity-collection-link.js.map

package/dist/entity-definition/links/entity-collection-link/entity-collection-link.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/entity-definition/links/entity-collection-link/entity-collection-link.ts"],"sourcesContent":["import { Effect } from 'effect';\n\nimport { EntifixError } from '../../../base-entities/entifix-error/index.js';\nimport { Entity, EntityConstructor, EntityId } from '../../../types/Entity.js';\nimport { EntityLinkResolver } from '../entity-link/index.js';\n\nexport interface EntityCollectionLinkInit<TEntity extends Entity> {\n  ids?: EntityId[];\n  values?: TEntity[];\n}\n\n/**\n * A one-to-many reference. Like {@link EntityLink} it accepts either foreign\n * keys (lazy, resolved through an {@link EntityLinkResolver}) or embedded\n * instances, but for a collection of targets.\n */\nexport class EntityCollectionLink<TEntity extends Entity> {\n  // #region properties\n  readonly entityConstructor: EntityConstructor<TEntity>;\n  #ids: EntityId[];\n  #values?: TEntity[];\n  // #endregion\n\n  // #region constructors\n  constructor(\n    entityConstructor: EntityConstructor<TEntity>,\n    init?: EntityCollectionLinkInit<TEntity>,\n  ) {\n    this.entityConstructor = entityConstructor;\n    this.#values = init?.values;\n    this.#ids =\n      init?.ids ??\n      init?.values\n        ?.map(value => value.id)\n        .filter((id): id is EntityId => id != null) ??\n      [];\n  }\n  // #endregion\n\n  // #region methods\n  setIds(ids: EntityId[]): void {\n    this.#ids = ids;\n  }\n\n  setValues(values: TEntity[] | undefined): void {\n    this.#values = values;\n    if (values !== undefined) {\n      this.#ids = values\n        .map(value => value.id)\n        .filter((id): id is EntityId => id != null);\n    }\n  }\n\n  /**\n   * Fetches every referenced target through the resolver and caches the result.\n   */\n  reload(resolver: EntityLinkResolver): Effect.Effect<TEntity[], EntifixError> {\n    return Effect.forEach(\n      this.#ids,\n      id => resolver.resolve(this.entityConstructor, id),\n      { concurrency: 'unbounded' },\n    ).pipe(Effect.tap(values => Effect.sync(() => this.setValues(values))));\n  }\n\n  resolve(\n    resolver: EntityLinkResolver,\n  ): Effect.Effect<TEntity[], EntifixError> {\n    return this.#values !== undefined\n      ? Effect.succeed(this.#values)\n      : this.reload(resolver);\n  }\n  // #endregion\n\n  // #region accessors\n  get ids(): EntityId[] {\n    return this.#ids;\n  }\n\n  get values(): TEntity[] | undefined {\n    return this.#values;\n  }\n\n  get isLoaded(): boolean {\n    return this.#values !== undefined;\n  }\n  // #endregion\n}\n"],"names":["Effect","EntityCollectionLink","setIds","ids","setValues","values","undefined","map","value","id","filter","reload","resolver","forEach","resolve","entityConstructor","concurrency","pipe","tap","sync","succeed","isLoaded","init"],"mappings":";;AAAA,SAASA,MAAM,QAAQ,SAAS;IAmB9B,6DACA;AATF;;;;CAIC,GACD,OAAO,MAAMC;IAqBX,aAAa;IAEb,kBAAkB;IAClBC,OAAOC,GAAe,EAAQ;QAC5B,gCAAA,IAAI,EAAC,MAAA,QAAOA;IACd;IAEAC,UAAUC,MAA6B,EAAQ;QAC7C,gCAAA,IAAI,EAAC,SAAA,WAAUA;QACf,IAAIA,WAAWC,WAAW;YACxB,gCAAA,IAAI,EAAC,MAAA,QAAOD,OACTE,GAAG,CAACC,CAAAA,QAASA,MAAMC,EAAE,EACrBC,MAAM,CAAC,CAACD,KAAuBA,MAAM;QAC1C;IACF;IAEA;;GAEC,GACDE,OAAOC,QAA4B,EAA0C;QAC3E,OAAOZ,OAAOa,OAAO,CACnB,gCAAA,IAAI,EAAC,MAAA,OACLJ,CAAAA,KAAMG,SAASE,OAAO,CAAC,IAAI,CAACC,iBAAiB,EAAEN,KAC/C;YAAEO,aAAa;QAAY,GAC3BC,IAAI,CAACjB,OAAOkB,GAAG,CAACb,CAAAA,SAAUL,OAAOmB,IAAI,CAAC,IAAM,IAAI,CAACf,SAAS,CAACC;IAC/D;IAEAS,QACEF,QAA4B,EACY;QACxC,OAAO,gCAAA,IAAI,EAAC,SAAA,aAAYN,YACpBN,OAAOoB,OAAO,CAAC,gCAAA,IAAI,EAAC,SAAA,YACpB,IAAI,CAACT,MAAM,CAACC;IAClB;IACA,aAAa;IAEb,oBAAoB;IACpB,IAAIT,MAAkB;QACpB,OAAO,gCAAA,IAAI,EAAC,MAAA;IACd;IAEA,IAAIE,SAAgC;QAClC,OAAO,gCAAA,IAAI,EAAC,SAAA;IACd;IAEA,IAAIgB,WAAoB;QACtB,OAAO,gCAAA,IAAI,EAAC,SAAA,aAAYf;IAC1B;IA/DA,aAAa;IAEb,uBAAuB;IACvB,YACES,iBAA6C,EAC7CO,IAAwC,CACxC;YAIEA;YACAA;QAbJ,4BAAA;;mBAAA,KAAA;;QACA,4BAAA;;mBAAA,KAAA;;QAQE,IAAI,CAACP,iBAAiB,GAAGA;QACzB,gCAAA,IAAI,EAAC,SAAA,WAAUO,wBAAAA,KAAMjB,MAAM;QAC3B,gCAAA,IAAI,EAAC,MAAA,SACHiB,gBAAAA,wBAAAA,KAAMnB,GAAG,oBACTmB,yBAAAA,eAAAA,KAAMjB,MAAM,qBAAZiB,aACIf,GAAG,CAACC,CAAAA,QAASA,MAAMC,EAAE,EACtBC,MAAM,CAAC,CAACD,KAAuBA,MAAM,iBAHxCa,OAIA,EAAE;IACN;AAkDF"}

package/dist/entity-definition/links/entity-collection-link/index.d.ts

@@ -0,0 +1,2 @@
+export * from './entity-collection-link.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/entity-definition/links/entity-collection-link/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/entity-definition/links/entity-collection-link/index.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAC"}

package/dist/entity-definition/links/entity-collection-link/index.js

@@ -0,0 +1,3 @@
+export * from './entity-collection-link.js';
+
+//# sourceMappingURL=index.js.map

package/dist/entity-definition/links/entity-collection-link/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/entity-definition/links/entity-collection-link/index.ts"],"sourcesContent":["export * from './entity-collection-link.js';\n"],"names":[],"mappings":"AAAA,cAAc,8BAA8B"}

package/dist/entity-definition/links/entity-link/entity-link.d.ts

@@ -0,0 +1,58 @@
+import { Effect } from 'effect';
+import { EntifixError } from '../../../base-entities/entifix-error/index.js';
+import { Entity, EntityConstructor, EntityId } from '../../../types/Entity.js';
+/**
+ * Framework-free seam a link uses to materialize its target entity. The concrete
+ * implementation lives at the composition root (a REST-backed resolver on the
+ * web, a Mongo-backed one on the backend) and is injected through Effect's
+ * context. Keeping the interface in `core` avoids an upward dependency on the
+ * repository contracts defined in `@entifix/business`.
+ */
+export interface EntityLinkResolver {
+    resolve<TEntity extends Entity>(entityConstructor: EntityConstructor<TEntity>, id: EntityId): Effect.Effect<TEntity, EntifixError>;
+}
+export interface EntityLinkInit<TEntity extends Entity> {
+    id?: EntityId;
+    value?: TEntity;
+}
+/**
+ * A reference from one entity to another. It models both shapes a raw payload
+ * can carry for a relation:
+ *
+ * - a **foreign key** — only the target id is known, so the entity is fetched
+ *   lazily through {@link reload};
+ * - **embedded data** — the target already arrived inline and was deserialized
+ *   into an instance, so {@link value} is populated and no fetch is needed.
+ *
+ * Resolution is expressed as an `Effect`, so the same link works in any
+ * environment: the caller provides an {@link EntityLinkResolver} backed by
+ * whatever adapter (REST, Mongo, …) fits the runtime.
+ */
+export declare class EntityLink<TEntity extends Entity> {
+    #private;
+    readonly entityConstructor: EntityConstructor<TEntity>;
+    constructor(entityConstructor: EntityConstructor<TEntity>, init?: EntityLinkInit<TEntity>);
+    /**
+     * Records the foreign key when the payload only referenced the target by id.
+     */
+    setId(id: EntityId): void;
+    /**
+     * Stores an already-materialized target (embedded payload or a completed
+     * reload) and keeps the id in sync with it.
+     */
+    setValue(value: TEntity | undefined): void;
+    /**
+     * Fetches the target through the resolver and caches it on the link. Always
+     * hits the resolver — use {@link resolve} to fetch only when not already
+     * loaded.
+     */
+    reload(resolver: EntityLinkResolver): Effect.Effect<TEntity, EntifixError>;
+    /**
+     * Returns the cached target if present, otherwise reloads it once.
+     */
+    resolve(resolver: EntityLinkResolver): Effect.Effect<TEntity, EntifixError>;
+    get id(): EntityId;
+    get value(): TEntity | undefined;
+    get isLoaded(): boolean;
+}
+//# sourceMappingURL=entity-link.d.ts.map

package/dist/entity-definition/links/entity-link/entity-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-link.d.ts","sourceRoot":"","sources":["../../../../src/entity-definition/links/entity-link/entity-link.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,OAAO,EAAE,YAAY,EAAE,MAAM,+CAA+C,CAAC;AAC7E,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAE/E;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,OAAO,SAAS,MAAM,EAC5B,iBAAiB,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAC7C,EAAE,EAAE,QAAQ,GACX,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,cAAc,CAAC,OAAO,SAAS,MAAM;IACpD,EAAE,CAAC,EAAE,QAAQ,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,UAAU,CAAC,OAAO,SAAS,MAAM;;IAE5C,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;gBAOrD,iBAAiB,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAC7C,IAAI,CAAC,EAAE,cAAc,CAAC,OAAO,CAAC;IAYhC;;OAEG;IACH,KAAK,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI;IAIzB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI;IAO1C;;;;OAIG;IACH,MAAM,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,YAAY,CAAC;IAM1E;;OAEG;IACH,OAAO,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,YAAY,CAAC;IAQ3E,IAAI,EAAE,IAAI,QAAQ,CAEjB;IAED,IAAI,KAAK,IAAI,OAAO,GAAG,SAAS,CAE/B;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;CAEF"}

package/dist/entity-definition/links/entity-link/entity-link.js

@@ -0,0 +1,79 @@
+import { _ as _class_private_field_loose_base } from "@swc/helpers/_/_class_private_field_loose_base";
+import { _ as _class_private_field_loose_key } from "@swc/helpers/_/_class_private_field_loose_key";
+import { Effect } from 'effect';
+var _id = /*#__PURE__*/ _class_private_field_loose_key("_id"), _value = /*#__PURE__*/ _class_private_field_loose_key("_value");
+/**
+ * A reference from one entity to another. It models both shapes a raw payload
+ * can carry for a relation:
+ *
+ * - a **foreign key** — only the target id is known, so the entity is fetched
+ *   lazily through {@link reload};
+ * - **embedded data** — the target already arrived inline and was deserialized
+ *   into an instance, so {@link value} is populated and no fetch is needed.
+ *
+ * Resolution is expressed as an `Effect`, so the same link works in any
+ * environment: the caller provides an {@link EntityLinkResolver} backed by
+ * whatever adapter (REST, Mongo, …) fits the runtime.
+ */ export class EntityLink {
+    // #endregion
+    // #region methods
+    /**
+   * Records the foreign key when the payload only referenced the target by id.
+   */ setId(id) {
+        _class_private_field_loose_base(this, _id)[_id] = id;
+    }
+    /**
+   * Stores an already-materialized target (embedded payload or a completed
+   * reload) and keeps the id in sync with it.
+   */ setValue(value) {
+        _class_private_field_loose_base(this, _value)[_value] = value;
+        if (value !== undefined && value.id != null) {
+            _class_private_field_loose_base(this, _id)[_id] = value.id;
+        }
+    }
+    /**
+   * Fetches the target through the resolver and caches it on the link. Always
+   * hits the resolver — use {@link resolve} to fetch only when not already
+   * loaded.
+   */ reload(resolver) {
+        return resolver.resolve(this.entityConstructor, _class_private_field_loose_base(this, _id)[_id]).pipe(Effect.tap((value)=>Effect.sync(()=>this.setValue(value))));
+    }
+    /**
+   * Returns the cached target if present, otherwise reloads it once.
+   */ resolve(resolver) {
+        return _class_private_field_loose_base(this, _value)[_value] !== undefined ? Effect.succeed(_class_private_field_loose_base(this, _value)[_value]) : this.reload(resolver);
+    }
+    // #endregion
+    // #region accessors
+    get id() {
+        var _class_private_field_loose_base__id;
+        var _class_private_field_loose_base__value;
+        return (_class_private_field_loose_base__id = _class_private_field_loose_base(this, _id)[_id]) != null ? _class_private_field_loose_base__id : (_class_private_field_loose_base__value = _class_private_field_loose_base(this, _value)[_value]) == null ? void 0 : _class_private_field_loose_base__value.id;
+    }
+    get value() {
+        return _class_private_field_loose_base(this, _value)[_value];
+    }
+    get isLoaded() {
+        return _class_private_field_loose_base(this, _value)[_value] !== undefined;
+    }
+    // #endregion
+    // #region constructors
+    constructor(entityConstructor, init){
+        Object.defineProperty(this, _id, {
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, _value, {
+            writable: true,
+            value: void 0
+        });
+        this.entityConstructor = entityConstructor;
+        _class_private_field_loose_base(this, _id)[_id] = init == null ? void 0 : init.id;
+        _class_private_field_loose_base(this, _value)[_value] = init == null ? void 0 : init.value;
+        if (_class_private_field_loose_base(this, _value)[_value] !== undefined && _class_private_field_loose_base(this, _id)[_id] == null) {
+            _class_private_field_loose_base(this, _id)[_id] = _class_private_field_loose_base(this, _value)[_value].id;
+        }
+    }
+}
+
+//# sourceMappingURL=entity-link.js.map

package/dist/entity-definition/links/entity-link/entity-link.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/entity-definition/links/entity-link/entity-link.ts"],"sourcesContent":["import { Effect } from 'effect';\n\nimport { EntifixError } from '../../../base-entities/entifix-error/index.js';\nimport { Entity, EntityConstructor, EntityId } from '../../../types/Entity.js';\n\n/**\n * Framework-free seam a link uses to materialize its target entity. The concrete\n * implementation lives at the composition root (a REST-backed resolver on the\n * web, a Mongo-backed one on the backend) and is injected through Effect's\n * context. Keeping the interface in `core` avoids an upward dependency on the\n * repository contracts defined in `@entifix/business`.\n */\nexport interface EntityLinkResolver {\n  resolve<TEntity extends Entity>(\n    entityConstructor: EntityConstructor<TEntity>,\n    id: EntityId,\n  ): Effect.Effect<TEntity, EntifixError>;\n}\n\nexport interface EntityLinkInit<TEntity extends Entity> {\n  id?: EntityId;\n  value?: TEntity;\n}\n\n/**\n * A reference from one entity to another. It models both shapes a raw payload\n * can carry for a relation:\n *\n * - a **foreign key** — only the target id is known, so the entity is fetched\n *   lazily through {@link reload};\n * - **embedded data** — the target already arrived inline and was deserialized\n *   into an instance, so {@link value} is populated and no fetch is needed.\n *\n * Resolution is expressed as an `Effect`, so the same link works in any\n * environment: the caller provides an {@link EntityLinkResolver} backed by\n * whatever adapter (REST, Mongo, …) fits the runtime.\n */\nexport class EntityLink<TEntity extends Entity> {\n  // #region properties\n  readonly entityConstructor: EntityConstructor<TEntity>;\n  #id: EntityId;\n  #value?: TEntity;\n  // #endregion\n\n  // #region constructors\n  constructor(\n    entityConstructor: EntityConstructor<TEntity>,\n    init?: EntityLinkInit<TEntity>,\n  ) {\n    this.entityConstructor = entityConstructor;\n    this.#id = init?.id;\n    this.#value = init?.value;\n    if (this.#value !== undefined && this.#id == null) {\n      this.#id = this.#value.id;\n    }\n  }\n  // #endregion\n\n  // #region methods\n  /**\n   * Records the foreign key when the payload only referenced the target by id.\n   */\n  setId(id: EntityId): void {\n    this.#id = id;\n  }\n\n  /**\n   * Stores an already-materialized target (embedded payload or a completed\n   * reload) and keeps the id in sync with it.\n   */\n  setValue(value: TEntity | undefined): void {\n    this.#value = value;\n    if (value !== undefined && value.id != null) {\n      this.#id = value.id;\n    }\n  }\n\n  /**\n   * Fetches the target through the resolver and caches it on the link. Always\n   * hits the resolver — use {@link resolve} to fetch only when not already\n   * loaded.\n   */\n  reload(resolver: EntityLinkResolver): Effect.Effect<TEntity, EntifixError> {\n    return resolver\n      .resolve(this.entityConstructor, this.#id)\n      .pipe(Effect.tap(value => Effect.sync(() => this.setValue(value))));\n  }\n\n  /**\n   * Returns the cached target if present, otherwise reloads it once.\n   */\n  resolve(resolver: EntityLinkResolver): Effect.Effect<TEntity, EntifixError> {\n    return this.#value !== undefined\n      ? Effect.succeed(this.#value)\n      : this.reload(resolver);\n  }\n  // #endregion\n\n  // #region accessors\n  get id(): EntityId {\n    return this.#id ?? this.#value?.id;\n  }\n\n  get value(): TEntity | undefined {\n    return this.#value;\n  }\n\n  get isLoaded(): boolean {\n    return this.#value !== undefined;\n  }\n  // #endregion\n}\n"],"names":["Effect","EntityLink","setId","id","setValue","value","undefined","reload","resolver","resolve","entityConstructor","pipe","tap","sync","succeed","isLoaded","init"],"mappings":";;AAAA,SAASA,MAAM,QAAQ,SAAS;IAwC9B,2DACA;AAjBF;;;;;;;;;;;;CAYC,GACD,OAAO,MAAMC;IAmBX,aAAa;IAEb,kBAAkB;IAClB;;GAEC,GACDC,MAAMC,EAAY,EAAQ;QACxB,gCAAA,IAAI,EAAC,KAAA,OAAMA;IACb;IAEA;;;GAGC,GACDC,SAASC,KAA0B,EAAQ;QACzC,gCAAA,IAAI,EAAC,QAAA,UAASA;QACd,IAAIA,UAAUC,aAAaD,MAAMF,EAAE,IAAI,MAAM;YAC3C,gCAAA,IAAI,EAAC,KAAA,OAAME,MAAMF,EAAE;QACrB;IACF;IAEA;;;;GAIC,GACDI,OAAOC,QAA4B,EAAwC;QACzE,OAAOA,SACJC,OAAO,CAAC,IAAI,CAACC,iBAAiB,EAAE,gCAAA,IAAI,EAAC,KAAA,MACrCC,IAAI,CAACX,OAAOY,GAAG,CAACP,CAAAA,QAASL,OAAOa,IAAI,CAAC,IAAM,IAAI,CAACT,QAAQ,CAACC;IAC9D;IAEA;;GAEC,GACDI,QAAQD,QAA4B,EAAwC;QAC1E,OAAO,gCAAA,IAAI,EAAC,QAAA,YAAWF,YACnBN,OAAOc,OAAO,CAAC,gCAAA,IAAI,EAAC,QAAA,WACpB,IAAI,CAACP,MAAM,CAACC;IAClB;IACA,aAAa;IAEb,oBAAoB;IACpB,IAAIL,KAAe;;;QACjB,8CAAO,gCAAA,IAAI,EAAC,KAAA,gGAAO,gCAAA,IAAI,EAAC,QAAA,4BAAL,uCAAaA,EAAE;IACpC;IAEA,IAAIE,QAA6B;QAC/B,OAAO,gCAAA,IAAI,EAAC,QAAA;IACd;IAEA,IAAIU,WAAoB;QACtB,OAAO,gCAAA,IAAI,EAAC,QAAA,YAAWT;IACzB;IAnEA,aAAa;IAEb,uBAAuB;IACvB,YACEI,iBAA6C,EAC7CM,IAA8B,CAC9B;QARF,4BAAA;;mBAAA,KAAA;;QACA,4BAAA;;mBAAA,KAAA;;QAQE,IAAI,CAACN,iBAAiB,GAAGA;QACzB,gCAAA,IAAI,EAAC,KAAA,OAAMM,wBAAAA,KAAMb,EAAE;QACnB,gCAAA,IAAI,EAAC,QAAA,UAASa,wBAAAA,KAAMX,KAAK;QACzB,IAAI,gCAAA,IAAI,EAAC,QAAA,YAAWC,aAAa,gCAAA,IAAI,EAAC,KAAA,QAAO,MAAM;YACjD,gCAAA,IAAI,EAAC,KAAA,OAAM,gCAAA,IAAI,EAAC,QAAA,QAAOH,EAAE;QAC3B;IACF;AAwDF"}

package/dist/entity-definition/links/entity-link/index.d.ts

@@ -0,0 +1,2 @@
+export * from './entity-link.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/entity-definition/links/entity-link/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/entity-definition/links/entity-link/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}

package/dist/entity-definition/links/entity-link/index.js

@@ -0,0 +1,3 @@
+export * from './entity-link.js';
+
+//# sourceMappingURL=index.js.map

package/dist/entity-definition/links/entity-link/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/entity-definition/links/entity-link/index.ts"],"sourcesContent":["export * from './entity-link.js';\n"],"names":[],"mappings":"AAAA,cAAc,mBAAmB"}

package/dist/entity-definition/links/entity-link-source/entity-link-source.d.ts

@@ -0,0 +1,74 @@
+import { EntifixError } from '../../../base-entities/entifix-error/index.js';
+import { Entity, EntityConstructor } from '../../../types/Entity.js';
+import { FilterGroup } from '../../../types/EntityFiltering.js';
+import { EntitySorting } from '../../../types/EntitySorting.js';
+/**
+ * A paged, filterable list of link targets, expressed as state plus the commands
+ * that change it.
+ *
+ * The member names match what a table already renders from, so a browse dialog
+ * forwards this object through untouched. It carries no Effect and no React: the
+ * hook that produces it lives in the integration layer, the components that
+ * consume it in the controls layer, and those two may not import each other —
+ * this contract in `core` is what lets them meet.
+ */
+export interface EntityLinkListView<TEntity extends Entity> {
+    items: ReadonlyArray<TEntity>;
+    totalItems: number;
+    currentPage: number;
+    pageSize: number;
+    isLoading: boolean;
+    error?: EntifixError;
+    filtering?: FilterGroup<TEntity>;
+    sorting?: EntitySorting<TEntity>;
+    onPageChange: (page: number) => void;
+    onPageSizeChange: (pageSize: number) => void;
+    onFilteringChange: (filtering: FilterGroup<TEntity>) => void;
+    onSortingChange: (sorting: EntitySorting<TEntity>) => void;
+}
+/** The quick half: a term, and the short list of matches it produces. */
+export interface EntityLinkQuickSearch<TEntity extends Entity> {
+    term: string;
+    setTerm: (term: string) => void;
+    options: ReadonlyArray<TEntity>;
+    isLoading: boolean;
+    error?: EntifixError;
+}
+/** The browse half: the full list view, plus the dialog holding it. */
+export interface EntityLinkBrowse<TEntity extends Entity> extends EntityLinkListView<TEntity> {
+    isOpen: boolean;
+    open: () => void;
+    close: () => void;
+}
+/**
+ * Everything an editor needs in order to set one relation, and nothing about how
+ * the targets are fetched.
+ *
+ * Two ways in, because they answer different questions: {@link quick} is
+ * "I know roughly what it is called", {@link browse} is "I need to look at the
+ * catalog and filter it". {@link selected} is the third, quieter one — a draft
+ * restored from storage holds an id and no instance, and an id is not a name.
+ */
+export interface EntityLinkSource<TEntity extends Entity> {
+    entityConstructor: EntityConstructor<TEntity>;
+    /** Reads a target's display label, per the owner's `linkLabelProperty`. */
+    labelOf: (entity: TEntity) => string;
+    /**
+     * The currently held id, resolved into something a form can use.
+     *
+     * `entity` is the whole target, not just its name, and that matters: a draft
+     * restored from storage holds ids only, so the instance a `linkSerialization:
+     * 'embedded'` member needs at submit is gone. Resolving the id was already
+     * happening for the label — carrying the instance out is what lets the form
+     * rehydrate its selection instead of quietly writing the `id` shape onto an
+     * `embedded` member.
+     */
+    selected: {
+        label?: string;
+        entity?: TEntity;
+        isLoading: boolean;
+    };
+    quick: EntityLinkQuickSearch<TEntity>;
+    browse: EntityLinkBrowse<TEntity>;
+}
+//# sourceMappingURL=entity-link-source.d.ts.map

package/dist/entity-definition/links/entity-link-source/entity-link-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-link-source.d.ts","sourceRoot":"","sources":["../../../../src/entity-definition/links/entity-link-source/entity-link-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,+CAA+C,CAAC;AAC7E,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAEhE;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB,CAAC,OAAO,SAAS,MAAM;IACxD,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,SAAS,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IACjC,OAAO,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACjC,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,gBAAgB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,iBAAiB,EAAE,CAAC,SAAS,EAAE,WAAW,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IAC7D,eAAe,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;CAC5D;AAED,yEAAyE;AACzE,MAAM,WAAW,qBAAqB,CAAC,OAAO,SAAS,MAAM;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED,uEAAuE;AACvE,MAAM,WAAW,gBAAgB,CAC/B,OAAO,SAAS,MAAM,CACtB,SAAQ,kBAAkB,CAAC,OAAO,CAAC;IACnC,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB,CAAC,OAAO,SAAS,MAAM;IACtD,iBAAiB,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC9C,2EAA2E;IAC3E,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC;IACrC;;;;;;;;;OASG;IACH,QAAQ,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;IACnE,KAAK,EAAE,qBAAqB,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC;CACnC"}

package/dist/entity-definition/links/entity-link-source/entity-link-source.js

@@ -0,0 +1,11 @@
+/**
+ * Everything an editor needs in order to set one relation, and nothing about how
+ * the targets are fetched.
+ *
+ * Two ways in, because they answer different questions: {@link quick} is
+ * "I know roughly what it is called", {@link browse} is "I need to look at the
+ * catalog and filter it". {@link selected} is the third, quieter one — a draft
+ * restored from storage holds an id and no instance, and an id is not a name.
+ */ export { };
+
+//# sourceMappingURL=entity-link-source.js.map