@ai-matrx/records 0.60.7 → 0.60.9

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog — @ai-matrx/records
 
+<!-- matrx-auto-git-docs-resolution-needed-delete-this-when-resolved — two versions follow: LOCAL first, then GITHUB. (LOCAL latest 2026-10-02 14:57; GITHUB latest 2026-10-02 14:58; LOCAL lacks 1 of GITHUB's 3 new lines; GITHUB lacks 17 of LOCAL's 17 new lines; recover: git show e40bf4695b:'apps/shared/records/CHANGELOG.md' / 5b7bf04c07:'apps/shared/records/CHANGELOG.md') Delete these three marker lines when resolved. -->
+
+## 0.60.9
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/records/v0.60.7..npm/records/v0.60.9 -- apps/shared/records`).
+No source changes intended and no consumer action required.
+
+## 0.61.0
+
+Lane PLATFORM-APP-DATA (asked by lane KINDS-GLUE, board items L12-1 … L12-7) — `ensureTable` makes the
+tables an app keeps.
+
+- **Placement, kind and drafts facts are stored.** `NewTableSpec` takes `keptByTheApp`, `keptFor`, `kind`,
+  `draftsFor`, `draftsStamp`; they are written on the table `ensureTable` (and `declareTable`) makes.
+- **`keptFor` is part of the address.** `ensureTable` finds a table by slug AND `keptFor`: a person's table and
+  an app's table of the same slug are different tables (`custom.table_ensure`, lane12_f).
+- **`homeId`.** A new table can be put in an existing Home the caller may change; no second Home is made. A Home
+  that is not in this organization (or archived, or not hers to change) is refused and nothing is made.
+- **Full column declarations.** `NewFieldSpec.optionsTableId` reuses an existing choice list (sent as
+  `config.options_table_id`); `NewFieldSpec.declaration` passes any other `custom.field_declare` key through
+  verbatim, applied last.
+- Proven on the clone as admin@admin.com and test@test.com: a 48-character slug, and a server path declaring the
+  code tier (`app.actor_tier = system`) acting as the person, both work. `drift` is unchanged.
+- `custom.table_find` now asks the record-store switch first (lane12_one_table_is_found_by_its_slug).
+
+Consumer action: none required. Needs `lane12_f_an_ensured_table_finds_its_kept_for_and_takes_a_home.sql` on
+production for `keptFor` matching and `homeId`; before it, `homeId` is ignored (a Home is made) and matching
+is by slug alone.
+<!-- matrx-auto-git-docs-resolution-needed-delete-this-when-resolved — GITHUB version below -->
+## 0.60.8
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/records/v0.60.7..npm/records/v0.60.8 -- apps/shared/records`).
+No source changes intended and no consumer action required.
+<!-- matrx-auto-git-docs-resolution-needed-delete-this-when-resolved — end of both versions -->
+
 ## 0.60.7
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see

package/README.md

@@ -73,6 +73,32 @@ not be read; `declared` is the store's sentence). It is `[]` on a birth and when
 it, so `long_text` is never a false `type` drift. This shape is the contract a release-time drift
 check reads (`parseFieldDrift` types a raw answer).
 
+### A table the app keeps
+
+```ts
+const outputs = await ensureTable(records, {
+  name: "Exercise flashcard outputs", slug: "agent_output_exercise_flashcard",
+  keptByTheApp: true, keptFor: "agent_output", kind: "exercise_flashcard",
+  homeId: sharedOutputsHome,                         // a NEW table goes in this Home; none is made
+  fields: [{ key: "body_region", label: "Body region", type: "select", optionsTableId }],
+});
+```
+
+`keptFor` is part of the address: a spec carrying it finds only a table kept for that word, and a spec
+without it never finds an app's table — a person's table and an app's table of one slug are different
+tables. `keptByTheApp`, `keptFor`, `kind`, `draftsFor` and `draftsStamp` are stored on the table it
+makes. `homeId` must be a live Home of this organization the caller may change, or nothing is made.
+`optionsTableId` reuses an existing choice list; `declaration` passes any other `custom.field_declare`
+key through as written.
+
+### When two tables share a slug, `tableFind` and `ensureTable` may differ
+
+A slug is not unique (older organizations hold a few duplicates). `tableFind` answers the oldest
+table of that slug **the caller may see**. `ensureTable` takes the oldest table of that slug
+**overall** and, if the caller may not know that one, refuses with the read door's own words rather
+than making a second table. So for a hidden oldest duplicate, `tableFind` returns a newer table while
+`ensureTable` refuses; both always agree when the caller can see the oldest one.
+
 Nothing here throws, and nothing here invents an answer. A door the store does
 not have yet is answered `door_absent`, naming the door AND the lane that owes
 it — `fieldPropose`, `tablePropose` and `mergeFieldResolve`

package/dist/core/index.cjs

@@ -44506,7 +44506,9 @@ function fieldDeclarationFor(field) {
     ...field.unit ? { unit: field.unit } : {},
     ...field.kind ? { kind: field.kind } : {},
     ...field.allowedTypes ? { allowed_types: field.allowedTypes } : {},
-    ...field.unique ? { rules: [{ kind: "unique" }] } : {}
+    ...field.unique ? { rules: [{ kind: "unique" }] } : {},
+    ...field.optionsTableId ? { config: { ...field.config ?? {}, options_table_id: field.optionsTableId } } : {},
+    ...field.declaration ?? {}
   };
 }
 function tableSpecFor(spec, fields, slug) {
@@ -44526,14 +44528,23 @@ function tableSpecFor(spec, fields, slug) {
     // AGT-1: a table a person made is agent-writable by declaration; the
     // organization turns it off, never this package.
     agent_writable: true,
-    default_sort: [{ field: titleField, direction: "asc" }]
+    default_sort: [{ field: titleField, direction: "asc" }],
+    ...spec.keptByTheApp !== void 0 ? { kept_by_the_app: spec.keptByTheApp } : {},
+    ...spec.keptFor ? { kept_for: spec.keptFor } : {},
+    ...spec.kind ? { kind: spec.kind } : {},
+    ...spec.draftsFor ? { drafts_for: spec.draftsFor } : {},
+    ...spec.draftsStamp ? { drafts_stamp: spec.draftsStamp } : {}
   };
 }
 async function ensureTable(client, spec) {
   const fields = spec.fields && spec.fields.length > 0 ? spec.fields : DEFAULT_FIELDS;
   const slug = spec.slug ?? tokenFor(spec.name);
   const ensured = await client.tableEnsure({
-    spec: { ...tableSpecFor(spec, fields, slug), fields: fields.map(fieldDeclarationFor) }
+    spec: {
+      ...tableSpecFor(spec, fields, slug),
+      ...spec.homeId ? { home_id: spec.homeId } : {},
+      fields: fields.map(fieldDeclarationFor)
+    }
   });
   if (!ensured.ok) return ensured;
   return {