@ai-matrx/agents 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,139 @@
 # Changelog
 
+## 0.10.0 — 2026-09-09
+
+**`@ai-matrx/agents/mandates` — clients stop typing mandate keys by hand.**
+
+A TypeScript client never declares a mandate: aidream's `declare_mandate` is the
+only declaration path in the system. Until now clients still *named* mandates
+with hand-typed string literals and local `mandates.ts` mirror files, so a typo,
+a rename, or a retired key failed at run time as a 404 nobody saw — and the
+release report had no way to resolve a client's references against the key set
+the client actually shipped.
+
+This release publishes that key set. `mandates/keys.generated.ts` is emitted by
+THE ONE GENERATOR (`aidream/scripts/mandates_generate.py`, stage (h)) from the
+in-process declarations — the same `declared_mandates()` the boot sync writes the
+database from — and cross-checked against the live `origin='code'` rows on every
+credentialed pass. The key set of every published version is committed beside it
+under `mandates/snapshots/keys.<version>.json` and ships in the tarball, so a
+scan can resolve a client's references against the key set of the exact version
+it depends on (Mandate Declaration & Usage Reporting, DESIGN § 4.5 step 2).
+
+### Consumer action
+
+Import keys from `@ai-matrx/agents/mandates`; hand-typed key literals and local
+`mandates.ts` mirrors are retired — lane L6.
+
+- `MANDATE_KEYS` — every declared key, keyed by THE IDENTIFIER RULE (`.` → `__`,
+  anything outside `[A-Za-z0-9_]` → `_`, a leading digit gets an `_`): so
+  `seo.keyword_classifier` is `MANDATE_KEYS.seo__keyword_classifier`.
+- `type MandateKey` — the union. Type every carrier parameter with it: a
+  made-up key then fails type-check instead of failing in production.
+  `as MandateKey` casts are the same defect the literals were.
+- `isMandateKey(x)` / `assertMandateKey(x, context?)` for anything that crossed
+  a wire (a URL segment, a stored preference, a row's `mandate_key`).
+- `MANDATE_FAMILIES` — prefix → members, for a family aidream declares from the
+  feature's own roster; `MandateFamilyMember<P>` types one member.
+- `mandateKeyOfApp(appSlug, surfaceSlug?)` / `mandateKeyOfShortcut(slug,
+  surfaceSlug?)` for the DB-authored `app.*` / `shortcut.*` families. They return
+  a branded `DynamicMandateKey`, deliberately **not** assignable to `MandateKey`
+  — no generated union can contain a row a user created five minutes ago. A
+  carrier that genuinely accepts either says `MandateKey | DynamicMandateKey`.
+- `RETIRING_MANDATE_KEYS` / `MANDATE_KEYS_META` — the deprecation list and the
+  aidream revision + generator version the key set came from.
+
+**Two-phase retire.** A key that stops being declared does not disappear: it is
+emitted `@deprecated retiring since <version>`, stays in the `MandateKey` union,
+and leaves only after three already-published versions have shipped it that way.
+A client that lags one release gets a deprecation warning with a remedy, never a
+hard type error it cannot act on until it upgrades.
+
+### Additive only
+
+No export was removed, renamed or re-signed. `./mandates` is a new subpath; every
+existing entry is untouched.
+
+## 0.9.2 — 2026-09-09
+
+**THE ARCHIVED-ITEMS LAW, APPLIED TO THE PICKER — the first instance of a
+platform-wide class.**
+
+Arman, 2026-09-09, asked whether the Public tab should hide archived agents
+like its other tabs (`common-docs/policies/archived-items.md`):
+
+> "Archived agents should be treated like all other archived items everywhere
+> within our codebase. … why does agents have to be any different than
+> workflows or employees or HR documents or anything else that we have?
+> They're not any different. They are the same, and they should be treated the
+> same. … everything should have an archive filter, and the default should
+> always hide archived, but seeing archived items should be one or two clicks
+> away. But don't go and do this for agents and forget that this is a system
+> wide decision for every single item everywhere in our system."
+
+### Consumer action: none
+
+No export was removed, renamed or re-signed. Additive only:
+`ARCHIVE_FILTER_OPTIONS`, `ARCHIVE_FILTER_ORDER`, `nextArchFilter`,
+`isAgentArchFilter`, `AgentArchFilterOption`, `AgentCatalogDefaults`,
+`agentArchiveFilterChipLabel` / `…StateLabel` / `…ControlLabel`,
+`agentListFooterLabel`, `AgentCatalog.consumerDefaults`,
+`useAgentListCore({ initialArchFilter })` and its `archivedHiddenCount` /
+`footerLabel` returns, plus `data-testid="agent-archive-filter"` /
+`"agent-list-footer"` (and their native `testID` twins). Every host adopts this
+by taking `latest`.
+
+### Behavioural deltas (all deliberate, the first was the defect)
+
+**THE BUILTIN ARCHIVE EXEMPTION IS DELETED.** `filterBuiltinTypeAgents` applied
+no archive filter, on the theory that "a builtin belongs to the platform and is
+never the user's to archive". The database disagreed: `Foundry Planner`
+(`001b22f6-fa4d-40c6-a1a4-8575d4d04379`) is an archived builtin, and it
+rendered at Public index 216, sat inside the "413 agents" badge and footer, and
+was pickable — while Mine / Shared / All hid their archived rows. One picker,
+two rules. `selectAgentTabCounts(...).system` and
+`selectTotalBuiltinAgentsCount` now count under the same rule the tab renders
+under, so badge == footer == rows holds on Public too.
+
+**THE ARCHIVE FILTER IS NOW A VISIBLE CONTROL, on web and native.** One chip on
+the filter bar with the platform's three states — *hide archived* (default) →
+*show all* → *archived only* → back — one click from opening the picker, on
+every tab, and present even for a consumer whose `visibleTabs` removes the tab
+strip. Its accessible name always says the state it is in and the state one
+click moves it to. It counts toward `activeFilterCount`, so a list showing
+archived rows offers the reset control that puts them away.
+
+**THE FOOTER IS HONEST ABOUT WHAT IT IS HIDING.** `agentListFooterLabel` prints
+`"412 agents · 4 archived hidden"`, `"416 agents · archived shown"` or
+`"3 archived shown"` — never a bare count that implies the list is everything.
+
+**THE DEFAULT IS A KNOB** (root law 6; law clause 6):
+`createAgentCatalog({ defaults: { archiveFilter } })` catalog-wide, platform
+default `"active"`, with a per-consumer override
+(`useAgentListCore({ initialArchFilter })`). An illegal value throws
+`AgentCatalogConfigError` rather than being silently ignored. `resetFilters`
+returns to the KNOB's value, not to the hardcoded platform one.
+
+### Proof, and how it can fail
+
+`catalog/__tests__/archive-law.test.ts` asserts, per archive state × per tab,
+that the rendered rows are exactly what the law says, that the badge and the
+footer are that same number, that the default hides archived rows on EVERY tab
+(Public included), that one action reveals them, and that the knob works and
+screams. The expectation is restated from the policy text and imports nothing
+from `catalog/selectors.ts`. Both shells (`catalog/react/archive-law.test.tsx`,
+`catalog/native/__tests__/archive-law.test.tsx`) measure the RENDERED screen.
+
+Falsifiability: reinstating the deleted exemption in `filterBuiltinTypeAgents`
+was verified to turn 6 of the 11 kernel tests red before shipping, and the old
+rule is written out in the suite so its answers are asserted to differ.
+`total-order-fixture.json` now carries an archived builtin, generated from the
+rule by `scripts/generate-total-order-fixture.mjs`.
+`parity-expected.json` is left byte-identical — it is a RECORDING of
+matrx-frontend, whose exemption is the defect — and the law is applied to that
+recording in exactly one place, with a test proving the transform changes 30
+cases and drops only builtin ids.
+
 ## 0.9.1 — 2026-09-08
 
 **TWO SCREENS TOLD THE SAME USER TWO DIFFERENT TRUTHS. BOTH ARE FIXED HERE, IN
@@ -112,7 +246,14 @@ had no ties, so F1 moved nothing that was already defined.
 
 **THE ONE PICKER NOW RENDERS ON REACT NATIVE — `@ai-matrx/agents/catalog/native`.**
 
-Matrx Mobile (Expo 54 / RN 0.81) was the last client still hand-rolling its
+> 🚨 **Correction, 2026-09-09 (Arman): this entry has NO CONSUMER.** The `matrx-mobile` repo
+> this release was built against is retired junk and is not a consumer of anything; there is no
+> current mobile package, and the new one has not been started. `./catalog/native` remains
+> published and gate-verified, but nothing ships on it. See common-docs
+> `projects/npm-package-extraction/DECISIONS.md` C32 / `systems/mandates/DECISIONS.md` D24. The
+> release notes below are preserved as written; the repo work they describe is void.
+
+The retired `matrx-mobile` app (Expo 54 / RN 0.81) was the last thing still hand-rolling its
 agent list. Its sheet showed four HARDCODED agents plus a Supabase read of a
 `prompts` table that **does not exist in the platform database** — a read whose
 PostgREST error was swallowed into an empty array, so the list silently never

package/dist/catalog/index.cjs

@@ -25,6 +25,8 @@ __export(catalog_exports, {
   AGENT_LIST_ITEMS_PER_PAGE: () => AGENT_LIST_ITEMS_PER_PAGE,
   AGENT_NONE_SENTINEL: () => AGENT_NONE_SENTINEL,
   AGENT_SEARCH_LIMIT: () => AGENT_SEARCH_LIMIT,
+  ARCHIVE_FILTER_OPTIONS: () => ARCHIVE_FILTER_OPTIONS,
+  ARCHIVE_FILTER_ORDER: () => ARCHIVE_FILTER_ORDER,
   AgentCatalogConfigError: () => AgentCatalogConfigError,
   AgentCatalogReadError: () => AgentCatalogReadError,
   DEFAULT_AGENT_CATALOG_LABELS: () => DEFAULT_AGENT_CATALOG_LABELS,
@@ -32,8 +34,12 @@ __export(catalog_exports, {
   MandateDefaultRowError: () => MandateDefaultRowError,
   SORT_OPTIONS: () => SORT_OPTIONS,
   _resetCatalogGlobalState: () => _resetCatalogGlobalState,
+  agentArchiveFilterChipLabel: () => agentArchiveFilterChipLabel,
+  agentArchiveFilterControlLabel: () => agentArchiveFilterControlLabel,
+  agentArchiveFilterStateLabel: () => agentArchiveFilterStateLabel,
   agentConsumerHasActiveFilters: () => agentConsumerHasActiveFilters,
   agentListEmptyLabel: () => agentListEmptyLabel,
+  agentListFooterLabel: () => agentListFooterLabel,
   agentMatchesArchiveFilter: () => agentMatchesArchiveFilter,
   agentMatchesSearch: () => agentMatchesSearch,
   applyAgentSortComparator: () => applyAgentSortComparator,
@@ -49,6 +55,7 @@ __export(catalog_exports, {
   filterBuiltinTypeAgents: () => filterBuiltinTypeAgents,
   filterUserTypeAgents: () => filterUserTypeAgents,
   getRegisteredAgentCatalog: () => getRegisteredAgentCatalog,
+  isAgentArchFilter: () => isAgentArchFilter,
   isMandateAgentId: () => isMandateAgentId,
   makeSelectFilteredAgents: () => makeSelectFilteredAgents,
   makeSelectFilteredAgentsCount: () => makeSelectFilteredAgentsCount,
@@ -64,6 +71,7 @@ __export(catalog_exports, {
   memoize1: () => memoize1,
   memoize2: () => memoize2,
   memoize3: () => memoize3,
+  nextArchFilter: () => nextArchFilter,
   orchestraDelegatesLine: () => orchestraDelegatesLine,
   orchestraDepthLine: () => orchestraDepthLine,
   orchestraLabel: () => orchestraLabel,
@@ -113,6 +121,24 @@ var SORT_OPTIONS = [
   { value: "name-desc", label: "Z \u2192 A" },
   { value: "category-asc", label: "Category" }
 ];
+var ARCHIVE_FILTER_ORDER = [
+  "active",
+  "both",
+  "archived"
+];
+var ARCHIVE_FILTER_OPTIONS = [
+  { value: "active", label: "Hide archived", chip: "Archive" },
+  { value: "both", label: "Show all", chip: "All + archived" },
+  { value: "archived", label: "Archived only", chip: "Archived only" }
+];
+function nextArchFilter(current) {
+  const index = ARCHIVE_FILTER_ORDER.indexOf(current);
+  if (index < 0) return ARCHIVE_FILTER_ORDER[0];
+  return ARCHIVE_FILTER_ORDER[(index + 1) % ARCHIVE_FILTER_ORDER.length];
+}
+function isAgentArchFilter(value) {
+  return value === "active" || value === "archived" || value === "both";
+}
 var AGENT_NONE_SENTINEL = "__none__";
 var DEFAULT_AGENT_CONSUMER_STATE = {
   tab: "mine",
@@ -735,6 +761,18 @@ function createAgentCatalog(config) {
       remedy: "pass `identity: { requireUserId() }` \u2014 never a silent anonymous read"
     });
   }
+  const archiveDefault = config.defaults?.archiveFilter;
+  if (archiveDefault !== void 0 && !isAgentArchFilter(archiveDefault)) {
+    throw new AgentCatalogConfigError({
+      code: "invalid_archive_default",
+      message: `defaults.archiveFilter was ${JSON.stringify(archiveDefault)}, which is not one of the three states of the platform archive filter`,
+      remedy: 'pass "active" (hide archived), "both" (show all) or "archived" (archived only)'
+    });
+  }
+  const consumerDefaults = {
+    ...DEFAULT_AGENT_CONSUMER_STATE,
+    ...archiveDefault ? { archFilter: archiveDefault } : {}
+  };
   const catalogId = config.catalogId ?? "default";
   const client = config.client;
   const identity = config.identity;
@@ -835,7 +873,7 @@ function createAgentCatalog(config) {
     return run;
   }
   function getConsumer(consumerId) {
-    return state.consumers[consumerId] ?? DEFAULT_AGENT_CONSUMER_STATE;
+    return state.consumers[consumerId] ?? consumerDefaults;
   }
   function writeConsumer(consumerId, next) {
     publish({
@@ -846,7 +884,7 @@ function createAgentCatalog(config) {
   function registerConsumer(consumerId, initial) {
     if (state.consumers[consumerId]) return;
     writeConsumer(consumerId, {
-      ...DEFAULT_AGENT_CONSUMER_STATE,
+      ...consumerDefaults,
       ...initial ?? {}
     });
   }
@@ -857,9 +895,7 @@ function createAgentCatalog(config) {
     publish({ ...state, consumers });
   }
   function setConsumerFilter(consumerId, patch) {
-    const current = state.consumers[consumerId] ?? {
-      ...DEFAULT_AGENT_CONSUMER_STATE
-    };
+    const current = state.consumers[consumerId] ?? { ...consumerDefaults };
     writeConsumer(consumerId, {
       ...current,
       ...patch,
@@ -876,9 +912,7 @@ function createAgentCatalog(config) {
     );
   }
   function setConsumerServerSearch(consumerId, args) {
-    const current = state.consumers[consumerId] ?? {
-      ...DEFAULT_AGENT_CONSUMER_STATE
-    };
+    const current = state.consumers[consumerId] ?? { ...consumerDefaults };
     const next = { ...current };
     if (args.matchedIds !== void 0) next.serverMatchedIds = args.matchedIds;
     if (args.isSearching !== void 0) next.isServerSearching = args.isSearching;
@@ -889,7 +923,7 @@ function createAgentCatalog(config) {
   }
   function resetConsumerFilters(consumerId) {
     if (!state.consumers[consumerId]) return;
-    writeConsumer(consumerId, { ...DEFAULT_AGENT_CONSUMER_STATE });
+    writeConsumer(consumerId, { ...consumerDefaults });
   }
   async function searchServer(query, deep = false) {
     const result = await searchAgentsOnServer(client, { query, deep });
@@ -1019,6 +1053,7 @@ function createAgentCatalog(config) {
     errorSink,
     notifier,
     canResolveMandates: transport !== void 0,
+    consumerDefaults,
     getState: () => state,
     subscribe: (listener) => {
       listeners.add(listener);
@@ -1096,6 +1131,26 @@ function shouldDefaultAgentListToPublicTab(args) {
   if (!args.agentsLoaded) return false;
   return args.ownedCount === 0;
 }
+function agentArchiveFilterChipLabel(archFilter) {
+  return ARCHIVE_FILTER_OPTIONS.find((o) => o.value === archFilter)?.chip ?? "Archive";
+}
+function agentArchiveFilterStateLabel(archFilter) {
+  return ARCHIVE_FILTER_OPTIONS.find((o) => o.value === archFilter)?.label ?? "Hide archived";
+}
+function agentArchiveFilterControlLabel(archFilter) {
+  return `Archive filter: ${agentArchiveFilterStateLabel(
+    archFilter
+  ).toLowerCase()}. Click for ${agentArchiveFilterStateLabel(
+    nextArchFilter(archFilter)
+  ).toLowerCase()}`;
+}
+function agentListFooterLabel(args) {
+  const { count, archFilter, archivedHiddenCount } = args;
+  if (archFilter === "archived") return `${count} archived shown`;
+  const base = `${count} agent${count !== 1 ? "s" : ""}`;
+  if (archFilter === "both") return `${base} \xB7 archived shown`;
+  return archivedHiddenCount > 0 ? `${base} \xB7 ${archivedHiddenCount} archived hidden` : base;
+}
 
 // catalog/score.ts
 function computeAgentSearchScore(agent, query) {
@@ -1306,8 +1361,7 @@ function filterUserTypeAgents(agents, consumer) {
     if (tab === "mine" && agent.isOwner !== true) return false;
     if (tab === "shared" && !(agent.isOwner === false && agent.accessLevel != null))
       return false;
-    if (archFilter === "active" && agent.isArchived) return false;
-    if (archFilter === "archived" && !agent.isArchived) return false;
+    if (!agentMatchesArchiveFilter(agent, archFilter)) return false;
     if (favFilter === "yes" && !agent.isFavorite) return false;
     if (favFilter === "no" && agent.isFavorite) return false;
     if (accessFilter === "owned" && agent.isOwner !== true) return false;
@@ -1337,9 +1391,10 @@ function filterUserTypeAgents(agents, consumer) {
   return sortFilteredAgents(filtered, consumer);
 }
 function filterBuiltinTypeAgents(agents, consumer) {
-  const { searchTerm, favFilter, includedCats, includedTags } = consumer;
+  const { searchTerm, favFilter, archFilter, includedCats, includedTags } = consumer;
   const serverMatched = new Set(consumer.serverMatchedIds);
   const filtered = agents.filter((agent) => {
+    if (!agentMatchesArchiveFilter(agent, archFilter)) return false;
     if (favFilter === "yes" && !agent.isFavorite) return false;
     if (favFilter === "no" && agent.isFavorite) return false;
     if (includedCats.length > 0) {
@@ -1457,6 +1512,15 @@ function agentMatchesArchiveFilter(agent, archFilter) {
   if (archFilter === "archived") return Boolean(agent.isArchived);
   return true;
 }
+function countBuiltinRows(agents, archFilter) {
+  let n = 0;
+  for (const a of agents) {
+    if (a.agentType !== "builtin") continue;
+    if (!agentMatchesArchiveFilter(a, archFilter)) continue;
+    n += 1;
+  }
+  return n;
+}
 function countUserRows(agents, archFilter, predicate) {
   let n = 0;
   for (const a of agents) {
@@ -1475,7 +1539,7 @@ var selectAgentTabCounts = memoize2(
     mine: countUserRows(agents, archFilter, isOwned),
     shared: countUserRows(agents, archFilter, isShared),
     all: countUserRows(agents, archFilter, isAny),
-    system: selectBuiltinTypeAgents(agents).length
+    system: countBuiltinRows(agents, archFilter)
   })
 );
 var selectTotalUserAgentsCount = memoize1(
@@ -1488,7 +1552,7 @@ var selectTotalSharedAgentsCount = memoize1(
   (agents) => countUserRows(agents, "active", isShared)
 );
 var selectTotalBuiltinAgentsCount = memoize1(
-  (agents) => selectBuiltinTypeAgents(agents).length
+  (agents) => countBuiltinRows(agents, "active")
 );
 var selectTotalFavoriteAgentsCount = memoize1(
   (agents) => countUserRows(agents, "active", isFavorite)