Merge remote-tracking branch 'origin/main' into claude/issue-21409-star-count-only

# Conflicts:
#	packages/spec/dropped-refinements.baseline.json

Author: claude

.changeset/20274-agent-memory-contract.md

@@ -0,0 +1,99 @@
+---
+'@objectstack/spec': minor
+'@objectstack/platform-objects': patch
+---
+
+feat(spec)!: an agent's `memory` contract states exactly what the runtime honours — `maxEntries` and `reflectionInterval` are required once long-term memory is enabled, `longTerm.store` is retired, and the block is `live`, enforced by the cloud AI runtime (#20274)
+
+**BREAKING** — `agent.memory` narrows to what the cloud AI runtime, the one runtime
+that executes agents, actually does with it. That runtime recalls the newest
+`maxEntries` distilled notes for the user before the first round, writes one note
+every `reflectionInterval` delivered interactions, evicts notes beyond `maxEntries`,
+and keeps them in its own database store. Before an agent's first turn it refused
+exactly the declarations this spec still accepted, so authoring now refuses them,
+by name, with a prescription (ADR-0049 enforce-or-remove):
+
+- **`longTerm.maxEntries` and `reflectionInterval` are required when
+  `longTerm.enabled` is true.** No default is declared for either: none has a
+  measured basis, and the runtime adds none.
+- **`reflectionInterval` is refused without an enabled `longTerm`** — a reflection
+  writes a long-term note, so with none enabled it would do nothing.
+- **`longTerm.store` is retired as a whole key.** The memory store is platform
+  infrastructure, not agent metadata: the runtime keeps the notes in its own
+  database store, and refused `vector` (the key's default, so what an omitted
+  `store` parsed to) and `redis`. Its old spellings `backend`, `storage` and
+  `provider` under `longTerm` are answered with the same prescription instead of
+  being steered onto `store`.
+
+`longTerm.enabled` is unchanged.
+
+### FROM → TO
+
+| before | what to write instead |
+| --- | --- |
+| `memory.longTerm.store` — any value, `database` included | delete the key; where the notes are kept is the platform's choice. |
+| `longTerm: { enabled: true, … }` without `maxEntries` | add `maxEntries`: how many distilled notes are kept for each user (an integer of at least 1). |
+| `longTerm: { enabled: true, … }` without `memory.reflectionInterval` | add `reflectionInterval`: how many delivered interactions pass between the reflections that write a note (an integer of at least 1). |
+| `memory.reflectionInterval` without `longTerm.enabled: true` | enable long-term memory with both numbers, or delete `reflectionInterval`. |
+
+**The one-line fix: declare `maxEntries` and `reflectionInterval` when `longTerm.enabled`; delete `store`.**
+`os migrate meta --from 17` lists the mechanical edits for existing sources (the
+`store` deletion); the two numbers are the author's to choose.
+
+Each refusal is a parse error at the key's own path, naming the key and the fix, and
+`store` also fails `tsc` (its input type is `never`).
+
+### The retirement kit
+
+- **Tombstone.** `longTerm.store` is a `retiredKey()` carrying the prescription; the
+  three old alias spellings moved from `aliases` to `guidance`, because an alias may
+  not steer an author onto a tombstone.
+- **The contract check** is a refinement on `memory` (`reflectionInterval` is
+  `longTerm`'s sibling), one `custom` issue per missing or misplaced key. A JSON
+  Schema cannot state a value-conditioned requirement in the closed projection list,
+  so the published `ai/Agent` schema (and the four installed-package schemas that
+  embed agents) names the site in `x-dropped-refinements`, recorded in
+  `dropped-refinements.baseline.json`.
+- **D2 conversion `agent-memory-long-term-store-removed`** (step 18, retired from the
+  load path): it deletes `store` from `memory.longTerm`, whatever it holds — the
+  delete is lossless, because no value of it ever chose a backend. Stored
+  `sys_metadata` agent rows and built artifacts replay it; one notice per agent. It
+  supplies neither number.
+- **D3 entry `agent-memory-store-retired-and-limits-required`** carries the judgement
+  the conversion cannot make: the two numbers an enabled `longTerm` now requires.
+- **`RETIRED_KEYS_BY_MAJOR[18]`** registers `ai/Agent:memory.longTerm.store`.
+- **No deprecation window**, per the project's startup-stage posture.
+
+### Describes and the liveness ledger
+
+- `agent.memory` drops `[EXPERIMENTAL — not enforced]`: it states that the cloud AI
+  runtime enforces it and that the open framework edition does not run agents.
+  `longTerm`, `enabled`, `maxEntries` and `reflectionInterval` each state what the
+  runtime does with them.
+- The ledger row moves `experimental` → `live`, citing the cloud reader
+  `agent-runtime.ts#compileAgentMemory` (via `AgentRuntime.resolveTurnGuardrails`),
+  the enforcement in `ai-service.ts` and the store `agent-memory.ts#AgentMemoryStore`,
+  as attested by the cloud seat's reading at cloud `ef5a4344`, `verifiedAt`
+  2026-10-02. `os lint` / `os validate` no longer warn
+  `liveness-experimental-property` on an agent that sets `memory`.
+- ⚠️ **The window, stated.** At `ef5a4344` the cloud reader still reads `store`: it
+  honours `database` only and refuses `vector` and `redis`. Cloud drops `store` in
+  that one reader once this release reaches its pin, and no earlier.
+
+### The agent form's help texts
+
+- The `memory` row's help text on the agent metadata form named short-term memory,
+  a key the schema refuses. It now states what memory does and that `maxEntries`
+  and `reflectionInterval` are required once long-term memory is enabled.
+- The neighbouring `planning` row named a strategy and a replan switch the schema
+  does not declare; it now states the one key it has, the iteration cap.
+- The `platform-objects` metadata-form catalogs follow: the English leaves are
+  regenerated, and the `zh-CN`, `ja-JP` and `es-ES` leaves are authored, not copied.
+
+⚠️ **The out-of-repo consumer population is NOT MEASURED.** `@objectstack/spec` is
+published, and tenant-authored agents were not measured. This repo authors no
+`longTerm` outside `packages/spec`, and no cloud built-in agent declares one.
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: registered agent-memory-long-term-store-removed, agent-memory-store-retired-and-limits-required -->

.changeset/21082-cube-member-json-stored-refused.md

@@ -0,0 +1,17 @@
+---
+"@objectstack/lint": minor
+---
+
+fix(lint)!: `os validate`, `os build` and `os lint` refuse an `analyticsCubes` dimension over a JSON-stored column, and a cube `count_distinct` measure over one, which the analytics door already refuses at query time
+
+Clause-②: no (narrowing)
+
+<!-- adr-0087: not-required (no-migration-prescription) a refusal at authoring of two cube member TARGETS the analytics door already refuses with 400 INVALID_FIELD at query time: an analyticsCubes dimension whose sql column is declared structured-JSON (json, composite, repeater, record, location, address, vector) or multi-value (multiselect, checkboxes, tags, or a select, radio, lookup, user, file or image declared multiple: true), and a count_distinct measure whose sql column is either. It is the cube face of the dataset dimension refusal, which declared this category for the same door. No authorable key, spelling, export or stored shape moves: CubeSchema keeps parsing every member, no stored row is read or rewritten, and which scalar part of a document, or which member of a list, an author meant to group on or count is not something a ledger entry can rewrite. The other categories are closed on facts: the package publishes (not unpublished); dataset-measure-aggregate-field-type-refused scopes itself to DatasetMeasureSchema rows and no ADR-0087 id covers a cube member (not already-registered); and the change is a rule verdict, not a declaration (not runtime-interface-only or type-surface-only). -->
+
+**BREAKING**: metadata that passed `os validate`, `os build` and `os lint` can now fail. An authored analytics cube (`defineStack({ analyticsCubes })`) is queried through the same analytics door as a compiled dataset, and that door refuses a query that groups by a JSON-stored column, or counts its distinct values, with `400 INVALID_FIELD` before any SQL is built. So such a member could be declared but never served, and until now no authoring rule read `analyticsCubes` at all. The dataset rule's two ids now judge cube members as well: `dimension-json-stored-field-refused` and `measure-aggregate-field-type-refused` (gating, `error`). It ships as `minor` under the launch-window convention for accept-set narrowings. No export is added or removed.
+
+**What is refused.** On a cube whose `sql` names an object the stack defines: a `dimensions` entry whose `sql` column is declared with a structured-JSON type (`json`, `composite`, `repeater`, `record`, `location`, `address`, `vector`) or a multi-value declaration (`multiselect`, `checkboxes`, `tags`, or a `select`, `radio`, `lookup`, `user`, `file` or `image` declared `multiple: true`); and a `measures` entry of `type: 'count_distinct'` whose `sql` column is either. The column is the member's `sql`: a column of the cube's object, or a relationship path read on the object its last hop reaches (the join the cube declares for that hop, else the lookup field's `reference`). The classes are `@objectstack/spec/data`'s `STRUCTURED_JSON_TYPES`, `isMultiValueField` and the `count_distinct` row of `AGGREGATE_FIELD_TYPE_COMPATIBILITY`, the predicates the door reads.
+
+**What an author sees now.** The finding names the cube, the member, the column, the object that declares it and its declaration, and says the analytics door refuses it with `400 INVALID_FIELD`. It names the route: group by, or count the distinct values of, a field that stores one scalar value; for a multi-value field, filter by one member with `$contains` in a record query. It is located at `analyticsCubes[N].dimensions.KEY.sql` or `analyticsCubes[N].measures.KEY.type`, where `KEY` is the member's key.
+
+**Unchanged.** Every dataset finding, word for word. A cube member over any other column, a single-value `select` or `lookup` included; a `count` measure, and a `sum`, `avg`, `min` or `max` measure, which this check does not judge; the row wildcard `'*'`; a member whose column does not resolve or declares no type; a cube whose `sql` names no object this stack defines. The runtime metadata write door: no authoring rule is dispatched for an `analytics_cube` save, and a `dataset` save's snapshot carries no cubes.

content/docs/deployment/validating-metadata.mdx

@@ -232,6 +232,18 @@ above declared `multiple: true`), is refused
 Group by a field that stores one value instead. Like the measure check, it
 stays silent when the field's type cannot be resolved.
 
+Both checks also judge the members of an analytics cube (`analyticsCubes`),
+because an authored cube is queried through the same analytics door. A cube
+dimension whose `sql` column is declared with a structured-JSON type or as a
+multi-value field is refused (`dimension-json-stored-field-refused`) at
+`analyticsCubes[N].dimensions.<key>.sql`, and so is a `count_distinct` measure
+over such a column (`measure-aggregate-field-type-refused`, at
+`analyticsCubes[N].measures.<key>.type`). The column is read where the door
+reads it: on the object the cube's `sql` names, or, for a relationship path,
+on the object the last hop reaches — the join the cube declares for that hop,
+else the lookup's `reference`. A cube's other measure types and the row
+wildcard `'*'` are not judged by this check.
+
 ### 7. Navigation exposing objects nobody can read
 
 Navigation and permissions are separate metadata, each valid on its own — so an

content/docs/references/ai/agent.mdx

@@ -58,7 +58,7 @@ const result = AIModelConfigSchema.parse(data);
 | **access** | `string[]` | optional | Who can chat with this agent |
 | **permissions** | `string[]` | optional | Required permission-set capabilities |
 | **planning** | `{ maxIterations: integer }` | optional | Autonomous reasoning and planning configuration |
-| **memory** | `{ longTerm?: object; reflectionInterval?: integer }` | optional | [EXPERIMENTAL — not enforced] Agent memory management. Parsed but no runtime consumer yet. |
+| **memory** | `{ longTerm?: object; reflectionInterval?: integer }` | optional | Agent memory (long-term notes recalled before each conversation and written by periodic reflection), enforced by the cloud AI runtime; the open framework edition does not run agents. |
 | **guardrails** | `{ maxTokensPerInvocation?: integer; maxExecutionTimeSec?: integer; blockedTopics?: string[] }` | optional | Safety guardrails for the agent (token budget, time limit, blocked topics), enforced per user turn by the cloud AI runtime; the open framework edition does not run agents. |
 | **structuredOutput** | `{ format: Enum<'json_object' \| 'json_schema'>; schema?: Record<string, any>; strict: boolean; retryOnValidationFailure: boolean; … }` | optional | Structured output contract for the agent's final answer (JSON format, schema, retries, fallback format, transform steps), enforced on every final answer by the cloud AI runtime; the open framework edition does not run agents. |
 | **protection** | `{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }` | optional | Package author protection block — lock policy for this agent. |
@@ -101,8 +101,8 @@ const result = AIModelConfigSchema.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **longTerm** | `{ enabled: boolean; store: Enum<'vector' \| 'database' \| 'redis'>; maxEntries?: integer }` | optional | Long-term / persistent memory |
-| **reflectionInterval** | `integer` | optional | Reflect every N interactions to improve behavior |
+| **longTerm** | `{ enabled: boolean; maxEntries?: integer }` | optional | Long-term memory: distilled notes kept per user and agent and recalled before each conversation |
+| **reflectionInterval** | `integer` | optional | Reflect every N delivered interactions: each reflection writes one distilled note to long-term memory. Required when longTerm.enabled is true, and refused without it |
 
 ### Nested Shape: `Agent.guardrails`
 

packages/lint/src/authoring-rules.ts

@@ -718,6 +718,12 @@ export const AUTHORING_RULES: readonly AuthoringRule[] = [
     // over the shipped dataset corpus before crossing, at the door's own
     // snapshot shape: 11 datasets (platform-objects 5, showcase 4, crm 1,
     // todo 1) — 0 findings, with a lit synthetic probe refused.
+    //
+    // [#21082] The rule also walks `analyticsCubes` (the cube leg, same two
+    // ids). That leg is CLI-only by construction, not by a narrowing here: a
+    // `dataset` write's snapshot carries no `analyticsCubes` (the context
+    // collections are `RuntimeStackContext`'s), so it reads nothing at this
+    // door, and an `analytics_cube` write has no `TYPE_TO_STACK_KEY` row.
     surfaces: CLI_AND_RUNTIME,
     runtimeTypes: ['dataset'],
     run: (stack) => validateDatasetMeasureAggregates(stack),

packages/lint/src/lint-liveness-properties.test.ts

@@ -119,12 +119,13 @@ describe('lintLivenessProperties', () => {
     expect(ruleOf(findings, 'nodes.outputSchema')).toBe(LIVENESS_DEAD_PROPERTY);
   });
 
-  it('warns on an experimental prop with no authorWarn of its own (agent.memory)', () => {
+  it('warns on an experimental prop with no authorWarn of its own (tool.outputSchema)', () => {
     // `experimental` warns implicitly — shouldWarn() treats a declared-but-
     // unenforced guarantee like an opted-in dead prop. Repointed from
-    // action.undoable in #3714, which turned out to have two objectui readers.
-    const findings = lintLivenessProperties({ agents: [{ name: 'ag1', memory: { kind: 'buffer' } }] });
-    const f = findings.find((x) => x.message.includes('`memory`'));
+    // action.undoable in #3714, which turned out to have two objectui readers,
+    // and from agent.memory in #20274, which the cloud AI runtime enforces.
+    const findings = lintLivenessProperties({ tools: [{ name: 't1', outputSchema: { type: 'object' } }] });
+    const f = findings.find((x) => x.message.includes('`outputSchema`'));
     expect(f).toBeDefined();
     expect(f!.rule).toBe('liveness-experimental-property');
   });
@@ -930,12 +931,12 @@ describe('lintLivenessProperties', () => {
   describe('never throws on a malformed collection item (#11385)', () => {
     it('flat TYPE_COLLECTIONS loop: skips a null item and keeps walking past it', () => {
       const findings = lintLivenessProperties({
-        // agent.memory is a real, currently-`experimental` ledger row (see
+        // tool.outputSchema is a real, currently-`experimental` ledger row (see
         // "warns on an experimental prop" above) — a real ledger witness,
         // not a synthetic one.
-        agents: [null, { name: 'ag1', memory: { kind: 'buffer' } }],
+        tools: [null, { name: 't1', outputSchema: { type: 'object' } }],
       });
-      expect(paths(findings).some((m) => m.includes('`memory`'))).toBe(true);
+      expect(paths(findings).some((m) => m.includes('`outputSchema`'))).toBe(true);
     });
 
     it('object walk: skips a null item and keeps walking past it', () => {
@@ -1596,12 +1597,12 @@ describe('a per-type ledger that could not be READ is reported once (#19276)', (
   });
 
   it('keeps walking the types whose ledgers ARE readable, and puts the fault first', () => {
-    // agent.memory is a real `experimental` row, so this proves the fault does
-    // not abort the pass: one type is dark, the rest still enforce, and the
-    // line that explains the darkness is the one a reader meets first.
+    // tool.outputSchema is a real `experimental` row, so this proves the fault
+    // does not abort the pass: one type is dark, the rest still enforce, and
+    // the line that explains the darkness is the one a reader meets first.
     const findings = lintLivenessPropertiesFromLedgerDir(
       ledgerDirWith((dir) => rmSync(join(dir, 'object.json'))),
-      { agents: [{ name: 'ag1', memory: { kind: 'buffer' } }] },
+      { tools: [{ name: 't1', outputSchema: { type: 'object' } }] },
     );
     expect(findings.map((f) => f.rule)).toEqual([LIVENESS_LEDGER_UNREADABLE, LIVENESS_EXPERIMENTAL_PROPERTY]);
     expect(findings[0].where).toBe("liveness ledger 'object'");