@asteby/metacore-runtime-react 47.1.0 → 49.0.0

package/src/primitives/aging.ts

@@ -0,0 +1,76 @@
+// AgingTable — antigüedad de saldos (CxC y CxP) como función pura.
+//
+// customers ya guarda aging_1_30 … aging_90_plus por cliente (refresh_credit_file).
+// Esta función es la MISMA regla para la UI (drill-down por documento, CxP que
+// hoy no la tiene) y para reportes: un solo lugar decide qué es «corriente».
+import { roundMoney } from '../business/format'
+
+export interface AgingBucket {
+    key: string
+    label: string
+    /** Días vencidos desde (inclusive). `current` usa -Infinity..0. */
+    from: number
+    /** Días vencidos hasta (inclusive). `null` = sin tope. */
+    to: number | null
+}
+
+export const DEFAULT_AGING_BUCKETS: AgingBucket[] = [
+    { key: 'current', label: 'Corriente', from: Number.NEGATIVE_INFINITY, to: 0 },
+    { key: 'd1_30', label: '1–30', from: 1, to: 30 },
+    { key: 'd31_60', label: '31–60', from: 31, to: 60 },
+    { key: 'd61_90', label: '61–90', from: 61, to: 90 },
+    { key: 'd90_plus', label: '90+', from: 91, to: null },
+]
+
+export interface AgingDoc {
+    party_id: string
+    party_name?: string
+    due_at: string | null // ISO date; null = vence al emitir
+    issued_at: string
+    balance: number
+}
+
+export interface AgingRow {
+    party_id: string
+    party_name?: string
+    buckets: Record<string, number>
+    total: number
+    overdue: number
+    oldest_overdue_days: number
+}
+
+const DAY = 86_400_000
+
+/** Días vencidos al corte (negativo = falta para vencer). Fechas en ISO (día). */
+export function daysOverdue(dueISO: string, asOfISO: string): number {
+    const due = Date.parse(dueISO.slice(0, 10) + 'T00:00:00Z')
+    const asOf = Date.parse(asOfISO.slice(0, 10) + 'T00:00:00Z')
+    return Math.round((asOf - due) / DAY)
+}
+
+export function bucketFor(days: number, buckets: readonly AgingBucket[] = DEFAULT_AGING_BUCKETS): string {
+    for (const b of buckets) if (days >= b.from && (b.to === null || days <= b.to)) return b.key
+    return buckets[buckets.length - 1].key
+}
+
+/** Agrupa por contraparte y tramo. Saldos ≤ 0 se ignoran (anticipos van aparte). */
+export function computeAging(docs: readonly AgingDoc[], asOfISO: string, buckets: readonly AgingBucket[] = DEFAULT_AGING_BUCKETS): { rows: AgingRow[]; totals: Record<string, number>; total: number } {
+    const rows = new Map<string, AgingRow>()
+    const totals: Record<string, number> = Object.fromEntries(buckets.map(b => [b.key, 0]))
+    for (const d of docs) {
+        if (d.balance <= 0) continue
+        const days = daysOverdue(d.due_at ?? d.issued_at, asOfISO)
+        const key = bucketFor(days, buckets)
+        const row = rows.get(d.party_id) ?? { party_id: d.party_id, party_name: d.party_name, buckets: Object.fromEntries(buckets.map(b => [b.key, 0])), total: 0, overdue: 0, oldest_overdue_days: 0 }
+        row.buckets[key] = roundMoney(row.buckets[key] + d.balance)
+        row.total = roundMoney(row.total + d.balance)
+        if (days > 0) {
+            row.overdue = roundMoney(row.overdue + d.balance)
+            row.oldest_overdue_days = Math.max(row.oldest_overdue_days, days)
+        }
+        totals[key] = roundMoney(totals[key] + d.balance)
+        rows.set(d.party_id, row)
+    }
+    const list = [...rows.values()].sort((a, b) => b.overdue - a.overdue || b.total - a.total)
+    return { rows: list, totals, total: roundMoney(list.reduce((s, r) => s + r.total, 0)) }
+}

package/src/primitives/allocation.ts

@@ -0,0 +1,104 @@
+// PaymentAllocator — reglas puras para aplicar un pago a varios documentos
+// abiertos (CxC: facturas del cliente; CxP: facturas del proveedor).
+//
+// Lo usan: cobro multi-factura + REP (customers / fiscal_mexico), CxC
+// «Registrar abono», CxP «Aplicar pago», abonos de apartado. Sin React y sin
+// host: la UI (PaymentAllocator) y el backend (wasm) pueden validar con lo mismo.
+import { roundMoney } from '../business/format'
+
+/** Documento abierto con saldo. `installments_paid` = parcialidades previas vigentes. */
+export interface OpenDocument {
+    id: string
+    number: string
+    issued_at: string // ISO date
+    due_at?: string | null
+    total: number
+    balance: number
+    currency: string
+    /** `PPD` / `PUE` u otro: el núcleo no lo interpreta; fiscal_mexico sí. */
+    payment_method?: string | null
+    installments_paid?: number
+    /** Extensiones de país (UUID, serie…). Pasan intactas a la línea. */
+    extra?: Record<string, unknown>
+}
+
+export interface Allocation {
+    document_id: string
+    amount: number
+    /** Saldo anterior / pagado / insoluto: lo que pide el DoctoRelacionado del REP y el estado de cuenta. */
+    balance_before: number
+    balance_after: number
+    /** Número de parcialidad de ESTE pago para el documento (1-based). */
+    installment: number
+}
+
+export type AllocationStrategy = 'oldest_due_first' | 'oldest_issued_first' | 'manual'
+
+export interface AllocationResult {
+    allocations: Allocation[]
+    applied: number
+    unapplied: number
+}
+
+function sortKey(d: OpenDocument, s: AllocationStrategy): string {
+    return s === 'oldest_issued_first' ? d.issued_at : (d.due_at ?? d.issued_at)
+}
+
+/** Reparte `amount` sobre `docs` según la estrategia. `manual` respeta `manual[id]`. */
+export function allocatePayment(
+    amount: number,
+    docs: readonly OpenDocument[],
+    strategy: AllocationStrategy = 'oldest_due_first',
+    manual: Readonly<Record<string, number>> = {},
+): AllocationResult {
+    let left = roundMoney(Math.max(0, amount))
+    const ordered = strategy === 'manual' ? [...docs] : [...docs].sort((a, b) => sortKey(a, strategy).localeCompare(sortKey(b, strategy)))
+    const allocations: Allocation[] = []
+    for (const d of ordered) {
+        if (left <= 0) break
+        const balance = roundMoney(d.balance)
+        if (balance <= 0) continue
+        const want = strategy === 'manual' ? roundMoney(manual[d.id] ?? 0) : balance
+        const pay = roundMoney(Math.min(want, balance, left))
+        if (pay <= 0) continue
+        allocations.push({
+            document_id: d.id,
+            amount: pay,
+            balance_before: balance,
+            balance_after: roundMoney(balance - pay),
+            installment: (d.installments_paid ?? 0) + 1,
+        })
+        left = roundMoney(left - pay)
+    }
+    const applied = roundMoney(allocations.reduce((s, a) => s + a.amount, 0))
+    return { allocations, applied, unapplied: roundMoney(Math.max(0, amount) - applied) }
+}
+
+export interface AllocationIssue {
+    code: 'over_balance' | 'over_amount' | 'currency_mismatch' | 'unapplied' | 'non_positive'
+    document_id?: string
+    severity: 'error' | 'warning'
+}
+
+/** Revisión previa a guardar (la UI la pinta en ValidationChecklist; el backend la repite). */
+export function validateAllocation(
+    amount: number,
+    currency: string,
+    docs: readonly OpenDocument[],
+    allocations: readonly Allocation[],
+    opts: { allowUnapplied?: boolean } = {},
+): AllocationIssue[] {
+    const byId = new Map(docs.map(d => [d.id, d]))
+    const issues: AllocationIssue[] = []
+    if (amount <= 0) issues.push({ code: 'non_positive', severity: 'error' })
+    for (const a of allocations) {
+        const d = byId.get(a.document_id)
+        if (!d) continue
+        if (a.amount > roundMoney(d.balance) + 0.005) issues.push({ code: 'over_balance', document_id: d.id, severity: 'error' })
+        if (d.currency !== currency) issues.push({ code: 'currency_mismatch', document_id: d.id, severity: 'error' })
+    }
+    const applied = roundMoney(allocations.reduce((s, a) => s + a.amount, 0))
+    if (applied > roundMoney(amount) + 0.005) issues.push({ code: 'over_amount', severity: 'error' })
+    else if (applied < roundMoney(amount) - 0.005) issues.push({ code: 'unapplied', severity: opts.allowUnapplied ? 'warning' : 'error' })
+    return issues
+}

package/src/primitives/approvals.ts

@@ -0,0 +1,103 @@
+// ApprovalInbox — tipos y cliente de la bandeja de aprobaciones del kernel
+// (dynamic/approvals.go, rutas /approvals*). Una sola bandeja para TODO lo que
+// declare `supervisor_policy`, `approval` o un guard `on_violation:
+// request_approval`, sin importar el addon (descuentos, crédito, OC por monto,
+// cancelación CFDI, ajustes negativos…).
+import type { ApiClient } from '../api-context'
+
+/** Espejo de dynamic.ApprovalRequest (JSON). jsonb llega como string. */
+export interface ApprovalRequestDTO {
+    id: string
+    addon_key: string
+    model_key: string
+    record_id: string
+    action_key: string
+    constraint_key: string
+    kind: 'constraint' | 'action' | 'explicit' | 'pin'
+    label: string
+    status: 'pending' | 'approved' | 'applied' | 'failed' | 'rejected' | 'expired'
+    requested_by: string
+    requested_by_role: string
+    requested_at: string
+    expires_at: string | null
+    roles: string | string[]
+    reason_required: boolean
+    payload: string | Record<string, unknown>
+    snapshot: string | Record<string, unknown>
+    violation: string | Record<string, unknown>
+    decided_by: string | null
+    decided_at: string | null
+    reason: string
+    error: string
+}
+
+export interface ApprovalListQuery {
+    status?: ApprovalRequestDTO['status']
+    kind?: ApprovalRequestDTO['kind']
+    model?: string
+    /** Solo las que yo pedí. */
+    mine?: boolean
+    /** Solo las que mis roles pueden decidir (default de la bandeja). */
+    for_me?: boolean
+    page?: number
+    per_page?: number
+}
+
+/** Categoría visible en la bandeja. El mapeo policy → categoría es extensible por addons. */
+export interface ApprovalCategory {
+    key: string
+    label: string
+    icon?: string
+    /** Coincide si devuelve true (p. ej. por action_key, constraint_key o model_key). */
+    match: (r: ApprovalRequestDTO) => boolean
+}
+
+const categories: ApprovalCategory[] = []
+
+/** Los addons registran su categoría al cargar (purchases: «Compras», fiscal_mexico: «Cancelación CFDI»…). */
+export function registerApprovalCategory(c: ApprovalCategory): () => void {
+    categories.push(c)
+    return () => {
+        const i = categories.indexOf(c)
+        if (i >= 0) categories.splice(i, 1)
+    }
+}
+
+export function categorize(r: ApprovalRequestDTO): string {
+    return categories.find(c => c.match(r))?.key ?? 'other'
+}
+
+export function groupApprovals(items: readonly ApprovalRequestDTO[]): Record<string, ApprovalRequestDTO[]> {
+    const out: Record<string, ApprovalRequestDTO[]> = {}
+    for (const r of items) (out[categorize(r)] ??= []).push(r)
+    return out
+}
+
+export function parseJSONField<T = Record<string, unknown>>(v: string | T | null | undefined): T | null {
+    if (v == null || v === '') return null
+    if (typeof v !== 'string') return v
+    try {
+        return JSON.parse(v) as T
+    } catch {
+        return null
+    }
+}
+
+/** Cliente fino sobre las rutas del kernel; la UI lo usa vía useApi(). */
+export function approvalsClient(api: ApiClient) {
+    const qs = (q: ApprovalListQuery) =>
+        Object.entries(q)
+            .filter(([, v]) => v !== undefined && v !== '')
+            .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+            .join('&')
+    return {
+        list: async (q: ApprovalListQuery = { status: 'pending', for_me: true }) => {
+            const res = await api.get(`/approvals?${qs(q)}`)
+            return { items: (res.data?.data ?? []) as ApprovalRequestDTO[], total: Number(res.data?.meta?.total ?? 0) }
+        },
+        count: async () => Number((await api.get('/approvals/count')).data?.data?.count ?? 0),
+        approve: (id: string, reason?: string) => api.post(`/approvals/${id}/approve`, { reason }),
+        reject: (id: string, reason: string) => api.post(`/approvals/${id}/reject`, { reason }),
+        approveWithPin: (id: string, pin: string, reason: string) => api.post(`/approvals/${id}/approve-pin`, { pin, reason }),
+    }
+}

package/src/primitives/contributions.ts

@@ -0,0 +1,255 @@
+// Registro de contribuciones federadas — cómo un addon mete secciones,
+// columnas, modales, fuentes de «Cargar desde» y vistas previas en la pantalla
+// de OTRO addon sin que ese addon lo conozca.
+//
+// Se monta sobre slotRegistry (slot.tsx) — no es un segundo sistema: cada
+// contribución es un SlotEntry con id canónico `doc:<kind>:<region>` — y añade
+// lo que slot no tiene: `requiresAddon` (se oculta solo si el addon no está
+// instalado o se desinstala en caliente), orden estable, `when` por documento y
+// carga perezosa del componente (import() del remote federado).
+//
+// Contrato estable para remotes federados: los tipos de este archivo. Todo
+// `register*` devuelve un disposer; el AddonLoader lo llama al desmontar o
+// recargar el remote y la contribución desaparece sin recargar la página.
+import { createElement, lazy, Suspense, type ComponentType } from 'react'
+import {
+    getModalComponent,
+    registerModalComponent,
+    subscribeActionComponents,
+    type ModalComponentEntry,
+} from '@asteby/metacore-sdk'
+import { slotRegistry } from '../slot'
+
+/** Regiones del DocumentEditor/DocumentPage donde se puede contribuir. */
+export type DocumentRegion =
+    | 'header.fields' // campos extra del encabezado (Uso CFDI, Método, Forma…)
+    | 'party.card' // filas extra en PartyCard (RFC, régimen, CP, CSF)
+    | 'lines.columns' // columnas de LinesGrid (clave SAT, DOT, almacén)
+    | 'side.panels' // paneles laterales (Revisión, PreviewPanel, crédito)
+    | 'body.sections' // secciones bajo los renglones (Reingreso a stock, Relación CFDI)
+    | 'footer.actions' // botones del ActionBar (Timbrar, Pedir autorización)
+
+export interface DocumentEditorContext {
+    kind: string // 'invoice' | 'credit_note' | 'payment' | 'purchase_order' | …
+    model: string // 'customers.Invoice'
+    values: Record<string, unknown>
+    mode: 'create' | 'edit' | 'view'
+}
+
+export interface DocumentContribution<P = DocumentContributionProps> {
+    /** Id estable `addon.region.name` (dedupe y orden). Re-registrar el mismo id reemplaza. */
+    id: string
+    kinds: string[] | '*'
+    region: DocumentRegion
+    /** Addon dueño. Si no está instalado, no se renderiza (y el server revalida). */
+    requiresAddon?: string
+    /** Mayor = primero. Default 0. */
+    priority?: number
+    when?: (ctx: DocumentEditorContext) => boolean
+    /** Componente o loader perezoso del remote (`() => import('fiscal_mexico/CfdiSection')`). */
+    component?: ComponentType<P>
+    load?: () => Promise<{ default: ComponentType<P> }>
+}
+
+/**
+ * Contribución resuelta: `component` siempre presente (si se registró con
+ * `load`, es un envoltorio lazy + Suspense que no pinta nada mientras carga).
+ */
+export type ResolvedDocumentContribution<P = DocumentContributionProps> = DocumentContribution<P> & {
+    component: ComponentType<P>
+}
+
+export interface DocumentContributionProps {
+    ctx: DocumentEditorContext
+    setValue: (key: string, value: unknown) => void
+    issues: { report: (key: string, issue: { severity: 'error' | 'warning'; message: string }) => void }
+}
+
+/** Predicado «¿está instalado?»; `useInstalledAddons` lo arma en React. */
+export type IsAddonInstalled = (addonKey: string) => boolean
+
+interface Entry {
+    c: ResolvedDocumentContribution<any>
+    dispose: () => void
+}
+
+const contribs = new Map<string, Entry>()
+const listeners = new Set<() => void>()
+let version = 0
+
+function notify() {
+    version += 1
+    for (const l of [...listeners]) l()
+}
+
+// Los modales viven en el store canónico del SDK (action-registry): cualquier
+// cambio ahí (Registry.registerModal, registerModalComponent, unbind) también
+// re-pinta a quien escucha contribuciones.
+subscribeActionComponents(notify)
+
+/** Suscripción para useSyncExternalStore (contribuciones y modales). */
+export function subscribeContributions(listener: () => void): () => void {
+    listeners.add(listener)
+    return () => {
+        listeners.delete(listener)
+    }
+}
+
+/** Versión monotónica: cambia en cada register/dispose. */
+export function contributionsVersion(): number {
+    return version
+}
+
+export function slotIdFor(kind: string, region: DocumentRegion): string {
+    return `doc:${kind}:${region}`
+}
+
+/** `load` → componente lazy envuelto en Suspense (fallback vacío: sin saltos de layout). */
+function lazyComponent<P>(load: () => Promise<{ default: ComponentType<P> }>): ComponentType<P> {
+    const Lazy = lazy(load) as unknown as ComponentType<any>
+    return (props: P) => createElement(Suspense, { fallback: null }, createElement(Lazy, props as any))
+}
+
+/**
+ * Registra la contribución y la publica en slotRegistry bajo cada `doc:<kind>:<region>`
+ * (kinds '*' → `doc:*:<region>`). Devuelve el disposer: AddonLoader lo llama al
+ * desmontar o recargar el remote (fiber), así la sección desaparece al desinstalar.
+ * Re-registrar el mismo `id` (recarga en caliente) reemplaza la anterior.
+ */
+export function registerDocumentContribution<P = DocumentContributionProps>(c: DocumentContribution<P>, source?: string): () => void {
+    if (!c.component && !c.load) throw new Error(`contribution ${c.id}: component o load es obligatorio`)
+    contribs.get(c.id)?.dispose()
+    const resolved = { ...c, component: c.component ?? lazyComponent(c.load!) } as ResolvedDocumentContribution<any>
+    const kinds = c.kinds === '*' ? ['*'] : c.kinds
+    const slotDisposers = kinds.map(k =>
+        slotRegistry.register(slotIdFor(k, c.region), resolved.component as ComponentType, {
+            priority: c.priority ?? 0,
+            source: source ?? c.requiresAddon ?? c.id,
+            owner: c.requiresAddon,
+        }),
+    )
+    let disposed = false
+    const entry: Entry = {
+        c: resolved,
+        dispose: () => {
+            if (disposed) return
+            disposed = true
+            slotDisposers.forEach(d => d())
+            if (contribs.get(c.id) === entry) contribs.delete(c.id)
+            notify()
+        },
+    }
+    contribs.set(c.id, entry)
+    notify()
+    return entry.dispose
+}
+
+/**
+ * Contribuciones aplicables a `region` para el documento `ctx`, ordenadas por
+ * prioridad (desc) y luego id. Pura: no lee React; `useDocumentContributions`
+ * la envuelve con useInstalledAddons.
+ */
+export function resolveContributions(
+    ctx: DocumentEditorContext,
+    region: DocumentRegion,
+    isInstalled: IsAddonInstalled,
+): ResolvedDocumentContribution<any>[] {
+    return [...contribs.values()]
+        .map(e => e.c)
+        .filter(c => c.region === region)
+        .filter(c => c.kinds === '*' || c.kinds.includes(ctx.kind))
+        .filter(c => !c.requiresAddon || isInstalled(c.requiresAddon))
+        .filter(c => !c.when || c.when(ctx))
+        .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0) || a.id.localeCompare(b.id))
+}
+
+// ---- Modales federados ------------------------------------------------------
+// ActionModalDispatcher resuelve `modal: "returns.settle_method"` con
+// requestFederatedAction (espera hasta 20 s). Este registro es su contraparte
+// declarativa: el addon registra la clave al cargar. Si el addon dueño no está
+// instalado, resolveFederatedModal devuelve null de inmediato y el dispatcher
+// usa el formulario genérico de la acción en vez de colgarse esperando.
+//
+// No hay mapa propio: es un alias del store canónico de modales por slug de
+// @asteby/metacore-sdk (registerModalComponent), el mismo donde escribe
+// `api.registry.registerModal` de AddonAPI.
+
+export interface FederatedModal<P = any> {
+    /** Clave `<addon>.<nombre>`, la misma que `modal` en el manifest. */
+    key: string // 'fiscal_mexico.import_cfdi'
+    addon: string
+    /** El dispatcher le pasa ActionModalProps (open, onOpenChange, action, model, record…). */
+    load: () => Promise<{ default: ComponentType<P> }>
+    /** Presente cuando el modal se registró ya cargado (`api.registry.registerModal`). */
+    component?: ComponentType<P>
+}
+
+/** Vista FederatedModal de cada entrada del store (identidad estable por entrada). */
+const views = new WeakMap<ModalComponentEntry, FederatedModal>()
+const modalComponents = new WeakMap<FederatedModal, ComponentType<any>>()
+/** Disposers de lo registrado por este alias (sólo __resetContributions los usa). */
+const aliasDisposers = new Set<() => void>()
+
+/**
+ * @deprecated Usa `registerModalComponent({ slug, load, owner })` de
+ * `@asteby/metacore-sdk` o `api.registry.registerModal` desde el plugin. Se
+ * mantiene como alias compatible: escribe en el mismo store.
+ */
+export function registerFederatedModal(m: FederatedModal): () => void {
+    const dispose = registerModalComponent({ slug: m.key, owner: m.addon, load: m.load, component: m.component })
+    const stored = getModalComponent(m.key)
+    if (stored) views.set(stored, m)
+    aliasDisposers.add(dispose)
+    return () => {
+        aliasDisposers.delete(dispose)
+        dispose()
+    }
+}
+
+function viewOf(e: ModalComponentEntry): FederatedModal {
+    let v = views.get(e)
+    if (!v) {
+        const component = e.component
+        v = {
+            key: e.slug,
+            addon: e.owner ?? '',
+            load: e.load ?? (async () => ({ default: component! })),
+            component,
+        }
+        views.set(e, v)
+    }
+    return v
+}
+
+/**
+ * Modal del slug en el store canónico, o null si no está registrado o su addon
+ * dueño no está instalado. Nunca espera.
+ */
+export function resolveFederatedModal(key: string, isInstalled: IsAddonInstalled): FederatedModal | null {
+    const m = getModalComponent(key)
+    return m && (!m.owner || isInstalled(m.owner)) ? viewOf(m) : null
+}
+
+/**
+ * Componente del modal resuelto: el ya cargado si lo hay; si no, un
+ * `React.lazy` memoizado por registro (no se re-crea en cada render; quien lo
+ * pinta lo envuelve en `<Suspense>`).
+ */
+export function federatedModalComponent<P = any>(m: FederatedModal<P>): ComponentType<P> {
+    if (m.component) return m.component
+    let C = modalComponents.get(m)
+    if (!C) {
+        C = lazy(m.load) as unknown as ComponentType<any>
+        modalComponents.set(m, C)
+    }
+    return C as ComponentType<P>
+}
+
+/** Solo para tests. */
+export function __resetContributions(): void {
+    for (const e of [...contribs.values()]) e.dispose()
+    contribs.clear()
+    for (const d of [...aliasDisposers]) d()
+    aliasDisposers.clear()
+    notify()
+}

package/src/primitives/document-kinds.ts

@@ -0,0 +1,62 @@
+// DocumentKind — un registro de tipos de documento comercial para que
+// factura, cotización, pedido, OC, NC, cobro/REP, factura de proveedor y OT usen
+// el MISMO DocumentEditor / DocumentPage. Cada addon declara su tipo (desde el
+// manifest `document_forms` o con registerDocumentKind) y el editor arma:
+// contraparte, renglones, fuentes de «Cargar desde», totales y vista previa.
+import type { DocumentFormPreview, DocumentFormSource } from '../types'
+
+export type PartyRole = 'customer' | 'supplier' | 'none'
+export type LinesMode =
+    | 'sale' // precio de venta, descuento, impuesto (factura, cotización, pedido)
+    | 'purchase' // costo, recepción pendiente (OC, factura de proveedor)
+    | 'credit' // cantidades ≤ facturado − acreditado (NC, devolución)
+    | 'allocation' // documentos abiertos a pagar (cobro / REP / pago a proveedor)
+    | 'workorder' // servicio + refacción, técnico, horas (OT)
+    | 'none'
+
+export interface DocumentKind {
+    key: string
+    label: string
+    model: string // ModelKey canónico ('customers.Invoice')
+    party: PartyRole
+    partyModel?: string // 'customers.Customer' | 'purchases.Supplier'
+    lines: LinesMode
+    /** Campo de renglones del modelo (one_to_many) o del payload de la acción. */
+    linesField?: string
+    sources?: DocumentFormSource[]
+    preview?: DocumentFormPreview
+    /** Estados del documento (StageMachine): los muestra StageStepper. */
+    stages?: string[]
+    /** Addon dueño del tipo (si no está, el tipo no se ofrece). */
+    addon: string
+}
+
+const kinds = new Map<string, DocumentKind>()
+
+export function registerDocumentKind(k: DocumentKind): () => void {
+    kinds.set(k.key, k)
+    return () => {
+        if (kinds.get(k.key) === k) kinds.delete(k.key)
+    }
+}
+
+export function getDocumentKind(key: string): DocumentKind | undefined {
+    return kinds.get(key)
+}
+
+export function listDocumentKinds(isInstalled: (addon: string) => boolean): DocumentKind[] {
+    return [...kinds.values()].filter(k => isInstalled(k.addon))
+}
+
+/** Tipos base que el core ya tiene (modelos verificados en addons main 9cd69bde). */
+export const CORE_DOCUMENT_KINDS: DocumentKind[] = [
+    { key: 'invoice', label: 'Factura', model: 'customers.Invoice', party: 'customer', partyModel: 'customers.Customer', lines: 'sale', linesField: 'items', addon: 'customers' },
+    { key: 'quote', label: 'Cotización', model: 'quotes.Quote', party: 'customer', partyModel: 'customers.Customer', lines: 'sale', linesField: 'items', addon: 'quotes' },
+    { key: 'sales_order', label: 'Pedido', model: 'customers.SalesOrder', party: 'customer', partyModel: 'customers.Customer', lines: 'sale', linesField: 'items', addon: 'customers' },
+    { key: 'payment', label: 'Cobro', model: 'customers.Payment', party: 'customer', partyModel: 'customers.Customer', lines: 'allocation', linesField: 'allocations', addon: 'customers' },
+    { key: 'credit_note', label: 'Nota de crédito', model: 'fiscal_mexico.CreditNote', party: 'customer', partyModel: 'customers.Customer', lines: 'credit', linesField: 'lines', addon: 'fiscal_mexico' },
+    { key: 'purchase_order', label: 'Orden de compra', model: 'purchases.PurchaseOrder', party: 'supplier', partyModel: 'purchases.Supplier', lines: 'purchase', linesField: 'items', addon: 'purchases' },
+    { key: 'supplier_invoice', label: 'Factura de proveedor', model: 'purchases.SupplierInvoice', party: 'supplier', partyModel: 'purchases.Supplier', lines: 'purchase', addon: 'purchases' },
+    { key: 'supplier_payment', label: 'Pago a proveedor', model: 'purchases.PurchasePayment', party: 'supplier', partyModel: 'purchases.Supplier', lines: 'allocation', addon: 'purchases' },
+    { key: 'work_order', label: 'Orden de trabajo', model: 'workshop.WorkOrder', party: 'customer', partyModel: 'customers.Customer', lines: 'workorder', linesField: 'items', addon: 'workshop' },
+]

package/src/primitives/index.ts

@@ -0,0 +1,23 @@
+// Primitivos de negocio — contrato estable para hosts y remotes federados.
+// Las funciones son puras (sin React ni host) salvo use-contributions; la UI y
+// el backend (wasm) pueden validar con las mismas reglas.
+//
+//  allocation       PaymentAllocator: allocatePayment / validateAllocation
+//                   (cobro multi-factura, REP, CxC «Registrar abono», CxP «Aplicar pago»).
+//  aging            AgingTable: computeAging / daysOverdue / bucketFor (antigüedad de saldos).
+//  approvals        ApprovalInbox: approvalsClient (rutas /approvals del kernel),
+//                   registerApprovalCategory / groupApprovals.
+//  contributions    Secciones y modales federados: registerDocumentContribution,
+//                   resolveContributions (pura), registerFederatedModal /
+//                   resolveFederatedModal. Todo register* devuelve su disposer.
+//  document-kinds   registerDocumentKind / listDocumentKinds / CORE_DOCUMENT_KINDS.
+//  panels           Tipos de PartyCard / TotalsPanel / PreviewPanel /
+//                   ValidationChecklist / LoadFromDocument + blockingChecks.
+//  use-contributions  Hooks: useDocumentContributions, useIsAddonInstalled.
+export * from './allocation'
+export * from './aging'
+export * from './approvals'
+export * from './contributions'
+export * from './document-kinds'
+export * from './panels'
+export * from './use-contributions'