@fayz-ai/core 0.9.0 → 0.11.0

package/dist/registry/entities.d.ts

@@ -0,0 +1,179 @@
+import { Registry } from './registry-class';
+import type { JsonSchema, RegistryEntryDescriptor, RegistrySource } from './registry-class';
+import type { FieldDef } from '../types/crud';
+/** The field-type vocabulary an entity may declare. */
+export type EntityFieldType = 'text' | 'richtext' | 'number' | 'boolean' | 'json' | 'image' | 'url' | 'ref' | 'point' | 'date' | 'datetime' | 'select';
+/** The vocabulary as a runtime value, for catalogs and I2 error messages.
+ *  `satisfies` + exhaustiveness keep the union and the list from drifting.
+ *  It also mirrors the CHECK on plg_entity_fields.type (migration 035) — a type
+ *  is a MODEL change, in both places at once, never an insert. */
+export declare const ENTITY_FIELD_TYPES: readonly ["text", "richtext", "number", "boolean", "json", "image", "url", "ref", "point", "date", "datetime", "select"];
+/**
+ * Bounds a value must respect beyond its type. Kept as data, not code, because
+ * a merchant defines these in the admin and they have to survive the round trip
+ * through plg_entity_fields.validation without anything being compiled.
+ */
+export interface EntityFieldValidation {
+    /** Numbers: inclusive bounds. */
+    min?: number;
+    max?: number;
+    /** Strings: inclusive length bounds. */
+    minLength?: number;
+    maxLength?: number;
+    /** Strings: an anchored-as-written regular expression. */
+    pattern?: string;
+}
+/** One choice of a `select` field. The value is what lands in custom_fields. */
+export interface EntityFieldOption {
+    value: string;
+    label?: string;
+}
+export interface EntityField {
+    type: EntityFieldType;
+    /** Human label — drives the admin form and the agent's understanding. */
+    label?: string;
+    help?: string;
+    required?: boolean;
+    default?: unknown;
+    /** `ref` only: the entity key this field points to (stores that entity's record id). */
+    entity?: string;
+    /** `select` only: the closed set of values. */
+    options?: readonly EntityFieldOption[];
+    validation?: EntityFieldValidation;
+}
+export type EntityReadAccess = 'public' | 'staff';
+/**
+ * Who reads and who writes. `write` is 'staff' only on purpose: shopper-writable
+ * entities (reviews) need the action/rate-limit layer (M7), not an RLS grant.
+ */
+export interface EntityAccess {
+    read: EntityReadAccess;
+    write: 'staff';
+}
+/** Where records live. Generic jsonb storage first (I5); promoting a hot entity
+ *  to typed columns changes THIS value, and nothing else callers see. */
+export interface EntityStorageDescriptor {
+    mode: 'generic' | 'dedicated';
+    /** Physical table. 'generic' mode shares it across entities. */
+    table: string;
+}
+export interface EntityDeclarationInput {
+    /** Human title (singular). Defaults to the key. */
+    title?: string;
+    description?: string;
+    fields: Record<string, EntityField>;
+    /** Only 'tenant' exists today: every record belongs to one store. */
+    scope?: 'tenant';
+    /** Default: staff-only both ways — public exposure is opt-in, never implied. */
+    access?: Partial<EntityAccess>;
+    /** Field-name tuples to index for querying/filtering. */
+    indexes?: readonly (readonly string[])[];
+    /** Field whose value titles a record in lists. Default: first text field. */
+    titleField?: string;
+    /** Fields blocks display by default (entityList). Default: every non-json field. */
+    displayFields?: readonly string[];
+}
+export interface EntityDeclaration {
+    key: string;
+    title: string;
+    description?: string;
+    fields: Record<string, EntityField>;
+    scope: 'tenant';
+    access: EntityAccess;
+    indexes: readonly (readonly string[])[];
+    titleField?: string;
+    displayFields: readonly string[];
+    storage: EntityStorageDescriptor;
+}
+/** The shared jsonb records table (see @fayz-ai/shop migrations 0030). */
+export declare const GENERIC_ENTITY_TABLE = "plg_entity_records";
+/** Structural record columns a declared field must not shadow. */
+export declare const RESERVED_ENTITY_FIELDS: readonly ["id", "slug", "entity", "tenant_id", "created_at", "updated_at"];
+export declare const entityDeclarationRegistry: Registry<EntityDeclaration>;
+/**
+ * Declare an entity. One call → registry entry on the uniform meta envelope,
+ * with the record JSON Schema as `propsSchema` — the same emission discipline
+ * as `defineBlock` (I1), so every catalog consumer reads entities and blocks
+ * with one parser.
+ */
+export declare function defineEntity(key: string, input: EntityDeclarationInput, meta?: {
+    source?: RegistrySource;
+    pluginId?: string;
+    since?: string;
+}): EntityDeclaration;
+/** Resolve a declaration or throw naming the valid set — the I2 contract. */
+export declare function resolveEntityDeclaration(key: string): EntityDeclaration;
+export declare function hasEntityDeclaration(key: string): boolean;
+/** All declared entity keys, sorted. */
+export declare function listEntityDeclarations(): string[];
+/** Test seam — a suite that declares entities must not leak into the next. */
+export declare function clearEntityDeclarations(): void;
+/**
+ * The JSON Schema one record's `data` is validated against — on write, in the
+ * admin form, and as the agent's generation contract. `additionalProperties:
+ * false` is the schema-level I2: a field the declaration does not know is an
+ * error, not silently-unfilterable baggage (the Medusa `metadata` disease).
+ */
+export declare function entityRecordSchema(declaration: Pick<EntityDeclaration, 'fields' | 'title' | 'description'>): JsonSchema;
+export interface EntityRecordIssue {
+    /** Dotted path into the record data ('hours', 'geo.lat'). */
+    path: string;
+    code: 'unknown-field' | 'missing-field' | 'invalid-value';
+    message: string;
+    /** The valid set, on unknown-id errors — what the agent corrects on. */
+    valid?: string[];
+}
+/**
+ * Validate one record's `data` against a declaration — the write gate every
+ * EntityStore implementation runs. Pure and total: returns issues, never throws.
+ */
+export declare function validateEntityRecordData(declaration: Pick<EntityDeclaration, 'fields'>, data: unknown): EntityRecordIssue[];
+/** The uniform envelope plus the entity-specific fields the agent reads. */
+export interface EntityDescriptor extends RegistryEntryDescriptor {
+    /** JSON Schema for a record's data (alias of `schema`, named for intent). */
+    recordSchema?: JsonSchema;
+    access: EntityAccess;
+    scope: 'tenant';
+    storage: EntityStorageDescriptor;
+    indexes: readonly (readonly string[])[];
+    titleField?: string;
+    displayFields: readonly string[];
+}
+/** Every declared entity reduced to its descriptor, sorted by key — what
+ *  describeStore publishes and the agent generates against. */
+export declare function describeEntities(): EntityDescriptor[];
+export interface EntityAdminForm {
+    entity: string;
+    title: string;
+    fields: FieldDef[];
+}
+/**
+ * The admin CRUD form for an entity, emitted from the declaration as data.
+ * Field order is declaration order; labels default to the field name; `ref`
+ * fields become relation pickers over the generic records table filtered to
+ * the target entity.
+ */
+export declare function entityAdminForm(declaration: EntityDeclaration): EntityAdminForm;
+export interface CustomFieldsDeclaration {
+    reference: string;
+    fields: Record<string, EntityField>;
+}
+export declare const customFieldsRegistry: Registry<CustomFieldsDeclaration>;
+/**
+ * Declare custom fields on a core record kind. One declaration per reference
+ * (re-declaring replaces — registry semantics, so an app's registry.tsx wins).
+ */
+export declare function defineCustomFields(reference: string, fields: Record<string, EntityField>, meta?: {
+    source?: RegistrySource;
+    pluginId?: string;
+}): CustomFieldsDeclaration;
+/**
+ * The declared half for a record kind. Returns an empty set rather than
+ * throwing: a tenant whose only fields came from the admin is the normal case,
+ * and the merge in @fayz-ai/core/fields is what completes the picture.
+ */
+export declare function declaredCustomFields(reference: string): Record<string, EntityField>;
+export declare function hasCustomFieldsDeclaration(reference: string): boolean;
+/** Test seam. */
+export declare function clearCustomFieldsDeclarations(): void;
+//# sourceMappingURL=entities.d.ts.map

package/dist/registry/entities.d.ts.map

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

package/dist/registry/extension-points.d.ts

@@ -0,0 +1,117 @@
+import { Registry } from './registry-class';
+import type { JsonSchema, RegistryEntryDescriptor, RegistrySource } from './registry-class';
+export type ExtensionPointMode = 'many' | 'escape';
+export interface ExtensionPointDeclaration {
+    /** Namespaced id: `namespace.point` (e.g. 'cart.lineAnnotation'). */
+    id: string;
+    description: string;
+    /** JSON Schema every invocation's input is checked against. */
+    input: JsonSchema;
+    /** JSON Schema every handler's (non-null) return is checked against. */
+    output: JsonSchema;
+    /**
+     * 'many' (default): any number of handlers, dependency-ordered, outputs
+     * collected. 'escape': at most ONE handler, `Output | null` return, non-null
+     * short-circuits the caller's default path (I4).
+     */
+    mode?: ExtensionPointMode;
+    source?: RegistrySource;
+    since?: string;
+}
+export interface ExtensionHandlerOptions {
+    /** Handler ids that must run before this one (dependency ordering, I3). */
+    after?: readonly string[];
+    description?: string;
+    source?: RegistrySource;
+    pluginId?: string;
+}
+export type ExtensionHandler<I = unknown, O = unknown> = (input: I) => O | Promise<O>;
+export declare const extensionPointRegistry: Registry<ExtensionPointDeclaration>;
+/**
+ * Declare an extension point. Idempotent per id (a re-declaration replaces the
+ * spec but keeps registered handlers), so HMR and repeated register-all calls
+ * are safe. The id must be namespaced `namespace.point` — two generated
+ * extensions can then never collide on a bare name (I3).
+ */
+export declare function defineExtensionPoint(declaration: ExtensionPointDeclaration): void;
+/**
+ * Register a handler at a point. Unknown point → hard error naming the valid
+ * set (I2). On an escape-valve point, a SECOND registration is a hard error
+ * naming who already holds it — the valve stays a valve, never a graph.
+ * Re-registering the SAME handler id replaces it (HMR safety), on any mode.
+ */
+export declare function registerExtensionHandler<I = unknown, O = unknown>(pointId: string, handlerId: string, handler: ExtensionHandler<I, O>, options?: ExtensionHandlerOptions): void;
+/** Remove one handler (test seams, HMR teardown). Unknown ids are a no-op. */
+export declare function unregisterExtensionHandler(pointId: string, handlerId: string): void;
+/**
+ * One collected result of a many-handler run: which handler said it, and what
+ * it said (already output-schema-checked).
+ */
+export interface ExtensionContribution<O = unknown> {
+    handlerId: string;
+    value: O;
+}
+/**
+ * Run a many-handler extension point: input checked once against the input
+ * schema, each handler's return checked against the output schema, results
+ * collected in dependency order. A handler returning `undefined`/`null`
+ * contributes nothing (that is how a handler declines) — anything else must
+ * satisfy the output schema.
+ *
+ * Failure semantics (M2): in dev every violation throws; in production a bad
+ * input logs and yields [] (the point is isolated), a bad output or a throwing
+ * handler logs and drops THAT handler's contribution only.
+ */
+export declare function runExtensionPoint<I = unknown, O = unknown>(pointId: string, input: I): Promise<ExtensionContribution<O>[]>;
+/**
+ * Run an escape valve (I4): `Output | null`. Null (or no registrant) means
+ * "take the default path"; a non-null return is schema-checked and returned
+ * for the caller to short-circuit with. In production a schema-invalid return
+ * or a throw logs and behaves as null — a broken escape must degrade to the
+ * default order path, never to a broken checkout.
+ */
+export declare function runEscapeValve<I = unknown, O = unknown>(pointId: string, input: I): Promise<O | null>;
+export interface ExtensionHandlerDescriptor {
+    id: string;
+    after: readonly string[];
+    description?: string;
+    source?: RegistrySource;
+    pluginId?: string;
+}
+export interface ExtensionPointDescriptor extends RegistryEntryDescriptor {
+    mode: ExtensionPointMode;
+    /** JSON Schema for the invocation input. */
+    inputSchema: JsonSchema;
+    /** JSON Schema for a handler's (non-null) return. */
+    outputSchema: JsonSchema;
+    /** Registered handlers, in registration order with their dependencies. */
+    handlers: ExtensionHandlerDescriptor[];
+}
+/** Every declared point with its schemas AND its registered handlers, sorted
+ *  by id — the enumerable surface an agent (and `fayz catalog`) reads. */
+export declare function describeExtensionPoints(): ExtensionPointDescriptor[];
+export declare function hasExtensionPoint(pointId: string): boolean;
+export declare function listExtensionPoints(): string[];
+/** Registered handler ids at a point, in registration order. Unknown point →
+ *  the same I2 hard error as every other lookup. */
+export declare function listExtensionHandlers(pointId: string): string[];
+/** Test seam — clears declarations AND handlers. */
+export declare function clearExtensionPoints(): void;
+/**
+ * Build a `withAfterHooks` handler map whose hooks run an extension point.
+ *
+ * `withAfterHooks(provider, handlers)` (core/integrations, the CONNECTORS.md
+ * outbound-sync seam) stays THE mechanism for post-write hooks — fire-and-
+ * forget, failures never break the app call. What it lacked was schema
+ * enforcement and enumerability; this bridge adds both by making the hook body
+ * a `runExtensionPoint` invocation: the point declares the input shape
+ * (`{ method, args, result }`), registered handlers are dependency-ordered and
+ * output-checked, and describeExtensionPoints lists them. One mechanism, now
+ * introspectable — not a competing one.
+ *
+ * Usage:
+ *   defineExtensionPoint({ id: 'shop.afterWrite', input: AFTER_WRITE_INPUT, … })
+ *   const provider = withAfterHooks(base, extensionAfterHooks('shop.afterWrite', ['placeOrder']))
+ */
+export declare function extensionAfterHooks<T extends object>(pointId: string, methods: readonly (keyof T & string)[]): Partial<Record<keyof T, (args: unknown[], result: unknown) => Promise<void>>>;
+//# sourceMappingURL=extension-points.d.ts.map

package/dist/registry/extension-points.d.ts.map

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

package/dist/registry/handles.d.ts

@@ -0,0 +1,41 @@
+import { Registry } from './registry-class';
+import type { RegistryMeta } from './registry-class';
+export declare const handleRegistry: Registry<unknown>;
+export interface RegisterHandleOptions {
+    /**
+     * Allow re-registering the name with a different value. Off by default:
+     * two modules silently fighting over one name is exactly the collision the
+     * namespace exists to prevent, so it throws unless the caller states the
+     * replacement is deliberate (config re-evaluation, HMR, tests).
+     */
+    replace?: boolean;
+}
+/**
+ * Register named code under a namespaced handle.
+ *
+ * Re-registering the SAME value under the same name is a no-op (idempotent, so
+ * a module evaluated twice does not fail). Re-registering a DIFFERENT value
+ * throws unless `replace: true` — see {@link RegisterHandleOptions}.
+ */
+export declare function registerHandle<T>(name: string, value: T, meta?: RegistryMeta, options?: RegisterHandleOptions): void;
+/** The value behind a handle, or undefined. Prefer {@link resolveHandle} in
+ *  hydration paths — an unknown handle there must be a hard error (I2). */
+export declare function getHandle<T = unknown>(name: string): T | undefined;
+export declare function hasHandle(name: string): boolean;
+/**
+ * Resolve a handle or throw naming the valid set — the I2 contract. This is
+ * the only lookup a document hydrator may use: an unknown handle silently
+ * dropped would render a store that LOOKS restored and is missing code.
+ */
+export declare function resolveHandle<T = unknown>(name: string): T;
+/** All registered handle names, sorted. */
+export declare function listHandles(): string[];
+/**
+ * Reverse lookup: the name a value was registered under, if any. Used by
+ * `exportStore` to serialize a code-valued config field as its handle name —
+ * which only works because handles hold the value by reference, not a copy.
+ */
+export declare function handleNameFor(value: unknown): string | undefined;
+/** Test helper — a suite that registers handles must not leak into the next. */
+export declare function clearHandles(): void;
+//# sourceMappingURL=handles.d.ts.map

package/dist/registry/handles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handles.d.ts","sourceRoot":"","sources":["../../src/registry/handles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAqBpD,eAAO,MAAM,cAAc,mBAAkC,CAAA;AAE7D,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AASD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,CAAC,EACR,IAAI,GAAE,YAAiB,EACvB,OAAO,GAAE,qBAA0B,GAClC,IAAI,CAqBN;AAED;2EAC2E;AAC3E,wBAAgB,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAElE;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAK1D;AAED,2CAA2C;AAC3C,wBAAgB,WAAW,IAAI,MAAM,EAAE,CAEtC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAKhE;AAED,gFAAgF;AAChF,wBAAgB,YAAY,IAAI,IAAI,CAEnC"}

package/dist/registry/index.d.ts

@@ -1,40 +1,27 @@
 import type { ComponentType } from 'react';
-/** A JSON Schema object (loosely typed; validated by tooling, not at runtime). */
-export type JsonSchema = Record<string, unknown>;
-export type RegistrySource = 'sdk' | 'plugin' | 'app';
-export interface RegistryMeta {
-    /** Human label for the platform editor. */
-    label?: string;
-    description?: string;
-    /** Where this artifact came from (for introspection / conflict reporting). */
-    source?: RegistrySource;
-    /** Owning plugin id, when source is 'plugin'. */
-    pluginId?: string;
-    /** JSON Schema for this artifact's props/config — drives the visual editor
-     *  and constrains AI generation. Optional but strongly encouraged. */
-    propsSchema?: JsonSchema;
-}
-export interface RegistryEntry<T> {
-    id: string;
-    value: T;
-    meta: RegistryMeta;
-}
-/** A typed, introspectable id→value map. Last registration wins (so an app's
- *  registry.tsx can override an SDK artifact by re-registering its id). */
-export declare class Registry<T> {
-    readonly kind: string;
-    private readonly entries;
-    constructor(kind: string);
-    register(id: string, value: T, meta?: RegistryMeta): void;
-    get(id: string): T | undefined;
-    getEntry(id: string): RegistryEntry<T> | undefined;
-    has(id: string): boolean;
-    list(): RegistryEntry<T>[];
-    ids(): string[];
-    clear(): void;
-}
-/** True for app-local custom artifacts (`custom:*`). */
-export declare function isCustomId(id: string): boolean;
+import { settingsToJsonSchema } from './block-schema';
+import { Registry } from './registry-class';
+import type { RegistryMeta } from './registry-class';
+export { Registry, isCustomId } from './registry-class';
+export type { JsonSchema, RegistrySource, RegistryMeta, RegistryEntry, RegistryEntryDescriptor, LoaderParamRef, LoaderPropRef, BlockDataNeed, BlockDataNeeds, } from './registry-class';
+export { settingsToJsonSchema };
+export { defaultPropsFromSettings, BLOCK_SETTING_TYPES } from './block-schema';
+export { handleRegistry, registerHandle, getHandle, hasHandle, resolveHandle, listHandles, handleNameFor, clearHandles, } from './handles';
+export type { RegisterHandleOptions } from './handles';
+export { loaderRegistry, defineLoader, resolveLoader, hasLoader, listLoaders, clearLoaders, describeLoaders, isLoaderParamRef, isLoaderPropRef, dataNeedKey, } from './loaders';
+export type { LoaderContext, LoaderImpl, LoaderDescriptor } from './loaders';
+export { ENTITY_FIELD_TYPES, GENERIC_ENTITY_TABLE, RESERVED_ENTITY_FIELDS, entityDeclarationRegistry, defineEntity, resolveEntityDeclaration, hasEntityDeclaration, listEntityDeclarations, clearEntityDeclarations, entityRecordSchema, validateEntityRecordData, describeEntities, entityAdminForm, customFieldsRegistry, defineCustomFields, declaredCustomFields, hasCustomFieldsDeclaration, clearCustomFieldsDeclarations, } from './entities';
+export type { EntityFieldType, EntityField, EntityReadAccess, EntityAccess, EntityStorageDescriptor, EntityDeclarationInput, EntityDeclaration, EntityRecordIssue, EntityDescriptor, EntityAdminForm as EntityAdminFormDescriptor, EntityFieldValidation, EntityFieldOption, CustomFieldsDeclaration, } from './entities';
+export type { BlockSetting, BlockSettingType, BlockSettingOption, BlockPreset, BlockStability, } from './block-schema';
+export { describeBlock, describeBlocks, isBlockEnabledOn, auditBlocks, summarizeBlockAudit, } from './block-catalog';
+export type { BlockDescriptor, BlockCatalogOptions, BlockAudit, BlockAuditLevel, } from './block-catalog';
+export type { RequiredBlockChild } from './registry-class';
+export { checkBlockConstraints, checkNodePlacement, checkBlockContext, repairBlockTree, } from './block-constraints';
+export type { BlockTreeNode, BlockConstraintRule, BlockConstraintViolation, BlockContextFinding, BlockTreeRepair, RepairBlockTreeResult, } from './block-constraints';
+export { checkAgainstSchema, formatSchemaIssues } from './schema-check';
+export type { SchemaIssue } from './schema-check';
+export { extensionPointRegistry, defineExtensionPoint, registerExtensionHandler, unregisterExtensionHandler, runExtensionPoint, runEscapeValve, describeExtensionPoints, hasExtensionPoint, listExtensionPoints, listExtensionHandlers, clearExtensionPoints, extensionAfterHooks, } from './extension-points';
+export type { ExtensionPointMode, ExtensionPointDeclaration, ExtensionHandlerOptions, ExtensionHandler, ExtensionContribution, ExtensionHandlerDescriptor, ExtensionPointDescriptor, } from './extension-points';
 export type MetricFormat = 'number' | 'currency' | 'percent' | 'duration' | 'rating';
 export interface MetricContext {
     tenantId?: string;
@@ -68,21 +55,34 @@ export declare const registerComponent: (id: string, c: AnyComponent, meta?: Reg
 export declare const getComponent: (id: string) => AnyComponent | undefined;
 export declare const registerBlock: (id: string, c: AnyComponent, meta?: RegistryMeta) => void;
 export declare const getBlock: (id: string) => AnyComponent | undefined;
-export declare const listBlocks: () => RegistryEntry<AnyComponent>[];
+export declare const listBlocks: () => import("./registry-class").RegistryEntry<AnyComponent>[];
+export declare const getBlockMeta: (id: string) => RegistryMeta | undefined;
+/**
+ * Register a block together with the schema that describes its props.
+ *
+ * The only thing this adds over {@link registerBlock} is compiling `settings`
+ * into `propsSchema` at registration, so the authored declaration and the
+ * machine contract cannot drift apart — which is exactly what happens whenever
+ * both are maintained by hand.
+ *
+ * Use this for any block a merchant, an editor or an agent is expected to
+ * configure. `registerBlock` stays for blocks that take no props, and for
+ * app-local code that has not been schematized yet.
+ */
+export declare const defineBlock: (id: string, component: AnyComponent, meta?: Omit<RegistryMeta, "propsSchema">) => void;
 export declare const registerPage: (id: string, c: AnyComponent, meta?: RegistryMeta) => void;
 export declare const getPage: (id: string) => AnyComponent | undefined;
 export declare const registerScaffold: (id: string, c: AnyComponent, meta?: RegistryMeta) => void;
 export declare const getScaffold: (id: string) => AnyComponent | undefined;
 export declare const registerMetric: (def: MetricDefinition, meta?: RegistryMeta) => void;
 export declare const getMetric: (id: string) => MetricDefinition | undefined;
-export declare const listMetrics: () => RegistryEntry<MetricDefinition>[];
+export declare const listMetrics: () => import("./registry-class").RegistryEntry<MetricDefinition>[];
 export declare const registerPlugin: (id: string, manifest: any, meta?: RegistryMeta) => void;
 export declare const getPlugin: (id: string) => any;
-export declare const listPlugins: () => RegistryEntry<any>[];
+export declare const listPlugins: () => import("./registry-class").RegistryEntry<any>[];
 export type PluginFactory = (config?: Record<string, unknown>) => any;
 export declare const pluginFactoryRegistry: Registry<PluginFactory>;
 export declare const registerPluginFactory: (id: string, factory: PluginFactory, meta?: RegistryMeta) => void;
 export declare const getPluginFactory: (id: string) => PluginFactory | undefined;
-export declare const listPluginFactories: () => RegistryEntry<PluginFactory>[];
-export {};
+export declare const listPluginFactories: () => import("./registry-class").RegistryEntry<PluginFactory>[];
 //# sourceMappingURL=index.d.ts.map

package/dist/registry/index.d.ts.map

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

package/dist/registry/loaders.d.ts

@@ -0,0 +1,55 @@
+import { Registry } from './registry-class';
+import type { JsonSchema, RegistryMeta, RegistryEntryDescriptor, LoaderParamRef, LoaderPropRef } from './registry-class';
+import type { BlockSetting } from './block-schema';
+/**
+ * What a loader gets to read from. `shop` is the ShopProvider port — typed as
+ * `unknown` here because core is backend-agnostic; the storefront layer pins
+ * it to its ShopProvider interface. Nothing else is provided on purpose:
+ * a loader that needs more than the port and its params is a loader that has
+ * smuggled in a dependency the resolver cannot see.
+ */
+export interface LoaderContext<TShop = unknown> {
+    shop: TShop;
+}
+/** A loader implementation: pure function of (params, ctx). */
+export type LoaderImpl<P extends Record<string, unknown> = Record<string, unknown>, R = unknown, TShop = unknown> = (params: P, ctx: LoaderContext<TShop>) => Promise<R> | R;
+export declare const loaderRegistry: Registry<LoaderImpl<Record<string, unknown>, unknown, unknown>>;
+/**
+ * Register a loader with its meta envelope. `settings` declare the params and
+ * compile to the params JSON Schema exactly as block settings compile to
+ * propsSchema — one declaration, no drift (I1).
+ */
+export declare function defineLoader<P extends Record<string, unknown>, R, TShop = unknown>(id: string, impl: LoaderImpl<P, R, TShop>, meta?: Omit<RegistryMeta, 'propsSchema'>): void;
+/**
+ * Resolve a loader or throw naming the valid set — the I2 contract. This is
+ * the only lookup a resolver may use: a data need whose loader silently
+ * resolved to nothing would render a page that LOOKS complete and is missing
+ * data.
+ */
+export declare function resolveLoader<P extends Record<string, unknown> = Record<string, unknown>, R = unknown, TShop = unknown>(id: string): LoaderImpl<P, R, TShop>;
+export declare function hasLoader(id: string): boolean;
+/** All registered loader ids, sorted. */
+export declare function listLoaders(): string[];
+/** Test seam — a suite that registers loaders must not leak into the next. */
+export declare function clearLoaders(): void;
+/** The uniform envelope plus the loader-specific fields the agent reads. */
+export interface LoaderDescriptor extends RegistryEntryDescriptor {
+    /** JSON Schema for the loader's params (alias of `schema`, named for intent). */
+    paramsSchema?: JsonSchema;
+    /** The authored param declarations, for editors that render pickers. */
+    params: readonly BlockSetting[];
+    /** One-line description of what the loader resolves to. */
+    output?: string;
+}
+/** Every loader reduced to its descriptor, sorted by id — what describeStore
+ *  publishes and the agent generates against. */
+export declare function describeLoaders(): LoaderDescriptor[];
+export declare function isLoaderParamRef(value: unknown): value is LoaderParamRef;
+export declare function isLoaderPropRef(value: unknown): value is LoaderPropRef;
+/**
+ * Canonical identity of one (loader, params) pair — the dedupe unit. Key-order
+ * insensitive and `undefined`-dropping, so two blocks declaring the same need
+ * in different spellings still resolve it once per page.
+ */
+export declare function dataNeedKey(loader: string, params?: Record<string, unknown>): string;
+//# sourceMappingURL=loaders.d.ts.map

package/dist/registry/loaders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loaders.d.ts","sourceRoot":"","sources":["../../src/registry/loaders.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,uBAAuB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAExH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAuBlD;;;;;;GAMG;AACH,MAAM,WAAW,aAAa,CAAC,KAAK,GAAG,OAAO;IAC5C,IAAI,EAAE,KAAK,CAAA;CACZ;AAED,+DAA+D;AAC/D,MAAM,MAAM,UAAU,CACpB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,CAAC,GAAG,OAAO,EACX,KAAK,GAAG,OAAO,IACb,CAAC,MAAM,EAAE,CAAC,EAAE,GAAG,EAAE,aAAa,CAAC,KAAK,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;AAE5D,eAAO,MAAM,cAAc,iEAAqC,CAAA;AAEhE;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,KAAK,GAAG,OAAO,EAChF,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,EAC7B,IAAI,GAAE,IAAI,CAAC,YAAY,EAAE,aAAa,CAAM,GAC3C,IAAI,CAON;AASD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,CAAC,GAAG,OAAO,EACX,KAAK,GAAG,OAAO,EACf,EAAE,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAIrC;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE7C;AAED,yCAAyC;AACzC,wBAAgB,WAAW,IAAI,MAAM,EAAE,CAEtC;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,IAAI,IAAI,CAEnC;AAED,4EAA4E;AAC5E,MAAM,WAAW,gBAAiB,SAAQ,uBAAuB;IAC/D,iFAAiF;IACjF,YAAY,CAAC,EAAE,UAAU,CAAA;IACzB,wEAAwE;IACxE,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;IAC/B,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;iDACiD;AACjD,wBAAgB,eAAe,IAAI,gBAAgB,EAAE,CAUpD;AAID,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAMxE;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAMtE;AAeD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,MAAM,CAExF"}