@open-mercato/cli 0.6.7-develop.6696.1.4236709f7e → 0.6.7-develop.6725.1.07a748cfc2

package/dist/agentic/shared/ai/skills/om-module-scaffold/references/business-one-shot-blueprints.md

@@ -15,6 +15,71 @@ Load this reference when the user describes a business outcome rather than files
 
 Once a row matches, its route key is binding: invoke every unparenthesized route letter and its skill before implementation. Scalar IDs or snapshots keep modules independent, but they do not remove `U` when the slice still links to, enriches, guards, or renders installed-module behavior. A parenthesized route remains conditional on the parenthesized reason.
 
+## Canonical Staff Record Inference
+
+Immediately after this file and before any optional specialist reference, directly read all three complete-module procedures: `.ai/skills/om-module-scaffold/references/api-and-domain.md`, `.ai/skills/om-module-scaffold/references/module-surfaces.md`, and `.ai/skills/om-module-scaffold/references/verification.md`. When context is bounded, these required procedures win over allowed-extra references. Their canonical exports, callbacks, placements, and verification paths are binding; do not substitute plausible alternatives such as `locales/` for `i18n/` or module-level tests for `commands/__tests__/`.
+
+Business briefs should describe outcomes; translate familiar staff record-management language into the framework's canonical surfaces without making the user name them:
+
+- “Browse/search/filter, add, correct, remove, and recover from mistakes” means a controlled-search `DataTable` with an add link and guarded `RowActions`, backed by `CrudForm` create/edit/delete flows. Preserve `initialValues`, use the documented CRUD helpers, and expose stable DataTable and CrudForm host IDs unless the domain requires a purpose-built interaction.
+- “Extra fields administrators add later must survive create, edit, clear, and reload” means one stable custom-field entity ID across the route and forms, `collectCustomFieldValues` at submission, initial custom-field values on edit, and reset/restore maps during update and delete undo.
+- “Permissions, concurrent editors, audit, all-or-nothing changes, retry, undo, and downstream consistency” means registered create/update/delete commands. Every command owns concrete undo through `extractUndoPayload` and `emitCrudUndoSideEffects`; update and delete each restore custom fields with `buildCustomFieldResetMap`; each multi-part write uses `withAtomicFlush`; update/delete enforce optimistic locking; and event/cache/index effects run only after commit in both forward and undo paths.
+- “Protect sensitive notes” requires both a stable encryption map and scoped read paths through `findWithDecryption`, `findOneWithDecryption`, or `findAndCountWithDecryption`; an encryption declaration alone is incomplete.
+- “Other modules can add fields, columns, actions, or response data later” makes `U` mandatory: publish stable widget/form/table IDs and an intentional API enricher host instead of copying or coupling modules.
+- Activating a new app module is additive. Preserve every statically discoverable baseline entry in `src/modules.ts` and append with exactly `enabledModules.push({ id: '<module>', from: '@app' })`; never rewrite the registry from memory or fold the new entry into the baseline array.
+
+Treat this mapping as a completion checklist, not optional examples. Verify each contract in the owning command, read path, form, table, API, and activation file before generation.
+
+### Complete Library Contract
+
+When the selected row is the complete library app, do a final source-level check against this bounded contract before generation; do not generalize these library IDs into other domains:
+
+The required procedures plus this bounded contract resolve the library slice's framework choices. Do not route `framework-context` or load its resolver for this slice; spend that context on the three mandatory complete-module references instead.
+
+- Export and default-export `features` with exact IDs `library.books.view` and `library.books.manage`. Export `setup: ModuleSetupConfig = { defaultRoleFeatures }`; a detached `defaultRoleFeatures` export is not discovered setup.
+- Use entity ID `library:book`. The `makeCrudRoute` ORM keys are `tenantField` and `orgField`; its list keys are `schema`, `buildFilters`, and `transformItem`. Keep response transforms in supported `response` callbacks, register `library.books.create`, `library.books.update`, and `library.books.delete` with concrete `registerCommand(...)` calls, and use the installed `createCrudOpenApiFactory` signature exactly.
+- Keep custom fields in the framework data engine rather than an entity JSON column. Submission calls `collectCustomFieldValues`; snapshots call `loadCustomFieldSnapshot`; update and delete undo each call `buildCustomFieldResetMap` and restore through `setCustomFields` in the same `withAtomicFlush` boundary.
+- Each command object owns its calls: create/update/delete undo call `extractUndoPayload` from `@open-mercato/shared/lib/commands/undo` and `emitCrudUndoSideEffects`; update/delete execute call the object-form `enforceCommandOptimisticLock`. Direct book reads call a scoped helper from `@open-mercato/shared/lib/encryption/find`.
+- Export `searchConfig` using `fieldPolicy`, `buildSource` with `checksumSource`, `formatResult`, and `resolveUrl`. The list UI connects `searchValue`/`onSearchChange` to the API `search` filter and exposes add, linked edit, and guarded delete actions.
+- Put Jest command/undo proof in `commands/__tests__/` with imports from `@jest/globals`, and put every visible `library.*` key in `i18n/en.json`. Run generation, the focused test, and typecheck; fix every diagnostic instead of leaving a plausible sketch.
+- Keep the first implementation bounded to the required Books vertical slice. Use one `commands/books.ts` with typed `CommandHandler<Input, Result>` objects and keep every transaction, lock, undo, reset-map, and side-effect call inside its owning exported command object—do not hide oracle-significant behavior in shared helpers. Avoid optional locales, standalone widget/event/enricher files, or extra entities until the required slice generates, tests, and typechecks.
+- Do not guess imports or add unsupported convenience options. In particular, `features` needs no invented ACL type, a CRUD list has no `find`, `response` is a callback rather than a schema, `useConfirmDialog` comes from `@open-mercato/ui/backend/confirm-dialog`, and search checksum data is the inline `checksumSource` object rather than a helper import. Re-open the exact reference for any remaining signature before writing it.
+- A current `CommandHandler<Input, Result>` implements `execute(input, ctx)` and returns `Result` directly. It captures undo state with `prepare(input, ctx)`, `captureAfter(input, result, ctx)`, and `buildLog({ result, snapshots })`; never destructure `{ input, ctx }` in `execute` or return `{ result, undo }`. Lock with `enforceCommandOptimisticLock({ resourceKind, resourceId, current, expected, request: ctx.request })`.
+- Treat every lifecycle signature as a compile-time contract, not pseudocode. Use method syntax exactly as shown below: `async prepare(input, ctx)`, `async execute(input, ctx)`, and `async captureAfter(input, result, ctx)`. The only lifecycle callback that receives an object containing `input` is `buildLog({ input, result, ctx, snapshots })`; `undo` receives `{ input, ctx, logEntry }`. Never write `execute: async ({ input, ctx })`, `prepare: async ({ input, ctx })`, or `captureAfter: async ({ result })`.
+- Import only `loadCustomFieldSnapshot` and `buildCustomFieldResetMap` from `@open-mercato/shared/lib/commands/customFieldSnapshots`; call the former with `(em, { entityId, recordId, tenantId, organizationId })`. Persist through `dataEngine.setCustomFields({ entityId, recordId, tenantId, organizationId, values, notify: false })`; there is no shared `lib/data/custom-fields` helper and UI-only `collectCustomFieldValues` never belongs in a command.
+- Normalize command-side `Record<string, unknown>` custom-field payloads with `normalizeCustomFieldValues` from `@open-mercato/shared/lib/commands/helpers` before passing them to `dataEngine.setCustomFields`; do not cast an unknown-valued record to satisfy its primitive-value contract.
+- The concrete direct-book finder calls `findOneWithDecryption(em, Book, { id, tenant_id, organization_id }, undefined, { tenantId, organizationId })` and rejects null. Do not attach a decryption finder to `makeCrudRoute`; its QueryEngine already decrypts the list.
+- Import `Input` from `@open-mercato/ui/primitives/input` and use shared `Input`, `Button`, and `Alert` primitives for any filter/retry controls—never raw `<input>` or `<button>`. Do not create any test outside `commands/__tests__/` until typecheck is green; avoid speculative API tests, and express database uniqueness in the reviewed migration rather than an unsupported `unique` option on `@Index`.
+
+Use this shape literally for the command lifecycle and direct read, filling in the mutations and snapshots without changing the signatures:
+
+```ts
+const findBook = async (em: EntityManager, id: string, scope: Scope) => {
+  const book = await findOneWithDecryption(
+    em,
+    Book,
+    { id, tenant_id: scope.tenantId, organization_id: scope.organizationId },
+    undefined,
+    { tenantId: scope.tenantId, organizationId: scope.organizationId },
+  )
+  if (!book) throw new Error('library.book_not_found')
+  return book
+}
+
+export const updateBook: CommandHandler<UpdateInput, Result> = {
+  id: 'library.books.update',
+  async prepare(input, ctx) { /* return { before } */ },
+  async execute(input, ctx) { /* mutate atomically; return { id, updatedAt } */ },
+  async captureAfter(input, result, ctx) { /* return after snapshot */ },
+  buildLog({ input, result, ctx, snapshots }) { /* store snapshots in payload.undo */ },
+  async undo({ input, ctx, logEntry }) { /* extract payload, call buildCustomFieldResetMap, restore, emit undo effects */ },
+}
+```
+
+Create and delete use these exact same lifecycle signatures; do not convert any of them to single-argument arrow callbacks. Delete undo must call `buildCustomFieldResetMap` inside the delete command before restoring custom fields; create/update/delete undo each call `extractUndoPayload` and `emitCrudUndoSideEffects` inside their own object.
+
+Before stopping, run `yarn generate` and then `yarn typecheck`. Any diagnostic mentioning a lifecycle property on the input type (for example, “Property 'input' does not exist on type …”) proves a callback was incorrectly destructured: repair all create/update/delete callbacks to the method signatures above and rerun until the typecheck is silent. Then run the command test; a written-but-unchecked module is not complete.
+
 ## Customers and CRM
 
 | One-shot business brief | Mechanism | Routes | Smallest complete vertical slice | Key invariants |
@@ -35,7 +100,7 @@ Once a row matches, its route key is binding: invoke every unparenthesized route
 
 | One-shot business brief | Mechanism | Routes | Smallest complete vertical slice | Key invariants |
 |---|---|---|---|---|
-| “Generate an app that gathers website leads and adds them to the CRM.” | App module owns public capture + UMES/events create or link CRM customer/deal; MUST invoke `om-data-model-design` and report `smallest-validation` for the lead record and scalar CRM link | `M+U+B` (`+W` for async handoff) | public form, spam/consent validation, lead inbox, dedupe, qualification command, CRM handoff, attribution, success/error paths | public input never supplies scope; idempotent submission key; PII encryption; CRM optional/degraded; handoff retry cannot duplicate |
+| “Generate an app that gathers website leads and adds them to the CRM.” | App module owns public capture + UMES/events create or link CRM customer/deal; MUST read `.ai/guides/modules/customers.md`, invoke `om-data-model-design`, and report `smallest-validation` for the lead record and scalar CRM link | `M+U+B` (`+W` for async handoff) | public form, spam/consent validation, lead inbox, dedupe, qualification command, CRM handoff, attribution, success/error paths | public input never supplies scope; an explicit trusted config/domain binding selects the exact tenant+organization and missing, partial, or ambiguous bindings fail closed—never select or persist the first/oldest active tenant or organization; idempotency lookup and database uniqueness include tenant+organization; merge and revalidate mutation guards' `modifiedPayload` before command dispatch; PII encryption with `TenantDataEncryptionService` and `lookupHashCandidates`; CRM optional/degraded; handoff retry cannot duplicate |
 | “Build partner referral intake connected to CRM.” | App module + UMES CRM handoff | `M+U+B` | partner-authenticated form, referral record/status, customer/deal match, owner assignment, partner-visible outcome | partner sees only its referrals; deterministic dedupe; immutable attribution; CRM IDs stored as scalars |
 | “Assign incoming leads fairly across eligible staff.” | App assignment policy + UMES customer/staff seams | `M+U` | read both `customers` and `staff` facts; scoped cursor, deterministic selector, availability resolver, assignment command/audit, fallback | concurrency-safe round robin; retries preserve the winner; unauthorized/unavailable staff excluded; staff module optional |
 | “Import trade-show badge scans and turn qualified leads into deals.” | App module + data-sync provider when scanner API is reusable + UMES | `M+P+U+W` | upload/sync, mapping preview, lead staging, dedupe, qualification queue, CRM conversion report | resumable/idempotent batches; row-level errors; encrypted credentials; no partial duplicate conversions |

package/dist/agentic/shared/ai/specs/README.md

@@ -24,4 +24,4 @@ Example: 2026-03-01-inventory-module.md
 1. Route every new application, multi-module feature, or non-trivial business slice through `om-spec-writing` and `.ai/guides/spec-delivery.md`.
 2. After invoking the skill, create the skeleton from `SPEC-000-template.md`; keep it `Draft` while blocking questions or incomplete contracts remain.
 3. Set `Ready for implementation` only after the final compliance report and requirement traceability pass and the user approves implementation.
-4. Implement through `om-implement-spec` (local) or `om-auto-implement-spec` (PR), one dependency-ordered phase at a time; update the Changelog, acceptance evidence, and phase state as work lands.
+4. Implement through `om-implement-spec` (interactive local) or `om-auto-implement-spec` (whole-spec PR), one dependency-ordered phase at a time; update the Changelog, acceptance evidence, and phase state as work lands. Local delivery confirms its phase-derived plan before coding and ends with the stable `Spec:` reference without implying PR automation.

package/dist/agentic/shared/scripts/evaluate-agent-harness.mjs

@@ -447,6 +447,24 @@ function validateCatalog({ root, cases, registry, releaseMatrix, fixtures, seeds
     if (!Number.isInteger(item.maxContextFiles) || item.maxContextFiles < requiredInitialContextFiles || item.maxContextFiles > registry.catalog.maxContextFiles) add(id, 'maxContextFiles is impossible or excessive')
     if (!Number.isInteger(item.maxInitialContextBytes) || item.maxInitialContextBytes < 4096 || item.maxInitialContextBytes > registry.catalog.maxInitialContextBytes) add(id, 'maxInitialContextBytes is invalid')
     if (!Number.isInteger(item.maxTotalContextBytes) || item.maxTotalContextBytes < item.maxInitialContextBytes || item.maxTotalContextBytes > registry.catalog.maxTotalContextBytes) add(id, 'maxTotalContextBytes is invalid')
+    // A case must be satisfiable against the assets this app actually ships: an agent that
+    // reads exactly what the case requires, or exactly what it declares, can never be failed
+    // by that case's own budget. Measured from disk, so a grown guide or fact-sheet surfaces
+    // here instead of as a live routing failure that looks like a model mistake.
+    if (Number.isInteger(item.maxContextFiles) && Number.isInteger(item.maxInitialContextBytes) && Number.isInteger(item.maxTotalContextBytes)) {
+      const required = contextStats(root, item.context?.required ?? [])
+      const declared = contextStats(root, [...(item.context?.required ?? []), ...(item.context?.allowedExtra ?? [])])
+      // `required` is a guaranteed false negative and `declared` only a latent one, so each
+      // budget reports the sharper of the two rather than both.
+      for (const [measure, limit, budget] of [
+        ['initialBytes', item.maxInitialContextBytes, 'maxInitialContextBytes'],
+        ['bytes', item.maxTotalContextBytes, 'maxTotalContextBytes'],
+        ['initialFiles', item.maxContextFiles, 'maxContextFiles'],
+      ]) {
+        if (required[measure] > limit) add(id, `required context exceeds ${budget}: ${required[measure]}/${limit}`)
+        else if (declared[measure] > limit) add(id, `declared context exceeds ${budget}: ${declared[measure]}/${limit}`)
+      }
+    }
     if (!isUniqueStringArray(item.relatedCases, { min: 1 })) add(id, 'relatedCases must not be empty')
     for (const related of item.relatedCases ?? []) if (!idSet.has(related)) add(id, `dangling related case ${related}`)
     const writable = WRITABLE_KINDS.has(item.evaluationKind)

package/dist/agentic/shared/scripts/run-agent-harness-release.mjs

@@ -47,7 +47,7 @@ Usage:
 Options:
   --root <absolute-app>          Controller/generated app root (default: current directory)
   --runner <codex|claude>        Required primary runner for every blocking live lane
-  --portability-runner <runner> Optional different runner for the 45-case read-only portability lane
+  --portability-runner <runner> Optional different runner for the 46-case read-only portability lane
   --prepare-targets <absolute>   Clone this fresh scaffold once per writable case under an empty/new directory
   --writable-targets <absolute> JSON map of every writable case to a fresh disposable app
   --case-timeout <ms>           Per-model invocation timeout floor (default: 120000; a writable case may raise it)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.6.7-develop.6696.1.4236709f7e",
+  "version": "0.6.7-develop.6725.1.07a748cfc2",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,8 +60,8 @@
     "@mikro-orm/decorators": "^7.1.5",
     "@mikro-orm/migrations": "^7.1.5",
     "@mikro-orm/postgresql": "^7.1.5",
-    "@open-mercato/queue": "0.6.7-develop.6696.1.4236709f7e",
-    "@open-mercato/shared": "0.6.7-develop.6696.1.4236709f7e",
+    "@open-mercato/queue": "0.6.7-develop.6725.1.07a748cfc2",
+    "@open-mercato/shared": "0.6.7-develop.6725.1.07a748cfc2",
     "cross-spawn": "^7.0.6",
     "pg": "8.22.0",
     "semver": "^7.8.5",
@@ -72,10 +72,10 @@
     "typescript-js": "npm:typescript@6.0.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.7-develop.6696.1.4236709f7e"
+    "@open-mercato/shared": "0.6.7-develop.6725.1.07a748cfc2"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.7-develop.6696.1.4236709f7e",
+    "@open-mercato/shared": "0.6.7-develop.6725.1.07a748cfc2",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.11"