Add catalog apply and sync: instantiate a position's duties onto a person (#34)

* Catalog instantiation: apply and sync a position's duty catalog

Adds two object-less actions and their handlers:

- duly_catalog_apply — instantiate every active duly_catalog_item for a
  position onto one or more people. Idempotent on (catalog_item, owner):
  a second apply creates nothing and reports the skips.
- duly_catalog_sync — replay catalog CADENCE edits (frequency, due_anchor,
  due_offset_days, lead_days, grace_days) onto derived duties. Never touches
  owner, status, timezone or the effective_* window; never touches a duty
  whose source is 'self'; reports duties from deactivated catalog items
  rather than deleting them.

The handler↔declaration wiring is asserted in tests because no author-time
gate covers it: an unregistered handler renders, is clickable, and 404s at
call time.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SqkTcrxUFci7nqXdbBSe2p

* Write pairKey's separator as an escape, not a raw NUL byte

The separator itself is right: a NUL cannot occur in a record id, so the
composite key cannot collide the way plain concatenation can - ('ab','c')
and ('a','bc') would otherwise produce the same key and silently skip a
duty that was never created.

Encoding it as a literal 0x00 in the source was the defect. It made git
treat catalog.handlers.ts as binary (Bin 0 -> 17555 bytes, no diff, no
blame, no review for the life of the file), left the separator invisible
in an editor, and would be dropped silently on copy-paste - degrading the
key back to plain concatenation with no error.

Now written as the \u0000 escape, so the file stays ASCII while the
runtime value is unchanged. pairKey is exported and the collision property
is pinned in tests, since the reason for the separator is not obvious and
would otherwise be "simplified" away.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SqkTcrxUFci7nqXdbBSe2p

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-warren

src/actions/catalog.actions.ts

@@ -0,0 +1,116 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { defineAction } from '@objectstack/spec';
+
+import {
+  CATALOG_APPLY_ACTION,
+  CATALOG_SYNC_ACTION,
+} from './catalog.handlers.js';
+
+/**
+ * Catalog instantiation — the onboarding path.
+ *
+ * Customers arrive with their catalog already written, usually as a
+ * spreadsheet. Taking a position has to mean "apply the list", not "hand-type
+ * 26 duties", or the rollout dies in week one.
+ *
+ * ── Why these are OBJECT-LESS and headless ────────────────────────────────
+ * Neither action operates on a record: `duly_catalog_apply` reads a whole
+ * position's worth of `duly_catalog_item` rows and writes `duly_duty` rows for
+ * several people at once. That makes it a GLOBAL action — no `objectName` — and
+ * an object-less action in protocol 17 has no UI home to declare.
+ * `global_nav` was removed from `ACTION_LOCATIONS` in @objectstack/spec 17
+ * (#6888, ADR-0049 enforce-or-remove): the console's ⌘K palette reads no action
+ * metadata, so the location never rendered. Every surviving location
+ * (`list_toolbar`, `list_item`, `record_*`) is bound to an object.
+ *
+ * So `locations: []` is the honest declaration the spec itself prescribes for
+ * this case — it keeps the param contract, the capability gate and the audit
+ * trail, and the action is invoked over the platform action route
+ * (`POST /api/v1/actions/global/duly_catalog_apply`) or MCP rather than from a
+ * button. Declaring a location a renderer does not serve would be the
+ * ADR-0078 declares-renders-does-nothing shape.
+ *
+ * ── Why `type: 'script'` with a `target` and no `body` ────────────────────
+ * The cadence maths and the idempotency probe are real code with real tests,
+ * not a sandboxed L1/L2 snippet. `target` names the handler registered from
+ * `src/actions/register-handlers.ts`; a `script` action with neither `body`
+ * nor `target` is rejected at author time precisely because it would otherwise
+ * render, be clickable, and 404 at call time.
+ */
+
+/**
+ * `duly_catalog_apply` — instantiate a position's catalog onto people.
+ *
+ * `position_code` is free text on purpose: a customer can load their catalog on
+ * day one, before positions are modelled in the platform, so this deliberately
+ * does NOT pick from `sys_position` and does NOT require a `sys_user_position`
+ * row to exist for the selected people.
+ */
+export const CatalogApplyAction = defineAction({
+  name: CATALOG_APPLY_ACTION,
+  label: 'Apply role catalog',
+  // Dialog copy, not the confirm prompt: an action that collects params and
+  // also sets `confirmText` shows two dialogs for one decision (#7278). The
+  // question is asked here, and the user's own Confirm sends it.
+  description:
+    'Create the duties this position owes for each person selected. Runs again safely — anyone who already has a duty from a catalog item is skipped, not duplicated.',
+  icon: 'user-plus',
+  type: 'script',
+  target: CATALOG_APPLY_ACTION,
+  locations: [],
+  variant: 'primary',
+  params: [
+    {
+      name: 'position_code',
+      label: 'Position',
+      type: 'text',
+      required: true,
+      placeholder: 'plant_compliance_officer',
+      helpText:
+        'Matches duly_catalog_item.position_code exactly. Free text — the position does not have to be modelled in the platform yet.',
+    },
+    {
+      name: 'users',
+      label: 'People',
+      type: 'user',
+      multiple: true,
+      required: true,
+      helpText: 'Each person gets their own copy of every active duty in this position\'s catalog.',
+    },
+  ],
+});
+
+/**
+ * `duly_catalog_sync` — replay catalog cadence edits onto instantiated duties.
+ *
+ * Cadence only (`frequency`, `due_anchor`, `due_offset_days`, `lead_days`,
+ * `grace_days`). `owner`, `status`, `timezone` and the `effective_*` window are
+ * local decisions the catalog has no business overwriting, and a retired
+ * catalog item is REPORTED rather than acted on — deleting someone's duties
+ * because a template was deactivated is a decision for a human.
+ *
+ * `position_code` is optional here and narrows the sweep. Sync rewrites
+ * authored cadence, so being able to run it for one position instead of the
+ * whole org is the difference between a correction and an incident.
+ */
+export const CatalogSyncAction = defineAction({
+  name: CATALOG_SYNC_ACTION,
+  label: 'Sync duties from catalog',
+  description:
+    'Replay cadence changes from the role catalog onto the duties created from it. Owner, status, timezone and the effective window are left alone; duties from a deactivated catalog item are reported, never deleted.',
+  icon: 'refresh-cw',
+  type: 'script',
+  target: CATALOG_SYNC_ACTION,
+  locations: [],
+  params: [
+    {
+      name: 'position_code',
+      label: 'Position',
+      type: 'text',
+      required: false,
+      placeholder: 'plant_compliance_officer',
+      helpText: 'Limit the sync to one position. Leave blank to sync every catalog-sourced duty.',
+    },
+  ],
+});