Merge remote-tracking branch 'origin/main' into claude/issue-6243-description-truth-sweep

Author: claude

.changeset/docs-gen-description-line-layout-and-nested-links.md

@@ -0,0 +1,58 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): docs-gen renders a module description as the markdown it was written as (#5553, #6136)
+
+Two independent defects in `scripts/lib/file-description.ts`, both from a
+transform applied at the wrong granularity. The block SELECTION rule #5059 added
+is untouched: all 185 sources that carried a module header still render one, and
+no page gained or lost an opening paragraph.
+
+**#5553 — line layout is content, not decoration.** The renderer dropped every
+blank line and joined what survived with `\n\n`, making each SOURCE LINE its own
+paragraph. Anything that legitimately wraps across lines was then cut in half by
+a paragraph boundary, and an inline code span cannot cross one, so both of its
+backticks fell out as literal text — `` `explain(principal, object, `` /
+`` operation)` `` on `security/explain`, and three more like it. The same pass
+escaped `{` and `}` everywhere including inside code, where a backslash is not
+an escape character but a character the reader sees, so pages published
+`` `\{ dialect, source \}` ``.
+
+The fix is to stop rewriting the layout: strip the ` * ` gutter and keep the
+lines as authored. Markdown's own rules then do what the issue asked for —
+consecutive lines are one paragraph, a blank line opens the next — and lists,
+headings, tables and code blocks keep working, which the literal space-join the
+issue floated would have broken on the 85 sources that write a list. Escaping and
+link resolution are now scoped to prose: fenced and indented code blocks are
+copied verbatim, and within prose a tokenizer keeps inline code spans out of
+reach.
+
+One construct is deliberately NOT reproduced as authored: an indented (4-space)
+code block is re-emitted as a fenced one. MDX dropped CommonMark's indented code
+blocks so that indentation could lay out JSX, so such a block reaches the MDX
+compiler as ordinary prose — and unescaped braces in prose are an expression.
+`data/date-macros` and `data/context-tokens` write their placeholder examples
+that way and are almost entirely braces; left indented they fail to compile
+("Could not parse expression with acorn"), and escaped instead they show `\{` in
+what is meant to be code. The target dialect has one spelling for a code block.
+
+Measured over the 185 rendered descriptions: paragraphs with unpaired backticks
+8 → 0 (`automation/flow-function`, `security/explain`, `shared/expression`,
+`system/settings-client`), and backslash-brace residue inside code 296 → 0 across
+33 pages. 32 pages get their fenced `@example` sample back as a real code block
+instead of one escaped paragraph per line, and 47 regain the indentation that
+made a nested list nested. The issue named five victim pages; `system/doc` is not
+among them because #5059 has since found its header documents `DocSchema` and
+stopped publishing it.
+
+**#6136 — a rewriter that ran over its own output.** The untitled
+`{@link <path>}` branch emits `[<path>](<route>)`, whose link TEXT is the path
+itself. The bare-source-path rewriter ran next over the whole string and matched
+that text, wrapping it a second time into a link nested in a link. Lookaround
+cannot express "not nested inside a link", so the rewriter is now applied per
+prose token with formed links excluded. `automation/etl` and
+`integration/connector` each get their "See also" back as one clickable link.
+
+169 reference pages are regenerated. No runtime, package export or protocol
+semantics change — this is the docs generator only.

.changeset/lucky-moons-smoke.md

@@ -0,0 +1,12 @@
+---
+'@objectstack/metadata-protocol': patch
+'@objectstack/objectql': patch
+---
+
+fix(metadata-protocol): boot 重水合按行的真实 package 绑定登记对象归属(#4636 裁 B 收官)
+
+`loadMetaFromDb` 的 object 分支从 `engine.find` 返回的行上读 `record.packageId`,而 `sys_metadata` 的列是 snake_case 的 `package_id` —— 该表达式恒为 `undefined || 'sys_metadata'`,于是每次重启都把**绑定了包**的对象 overlay 登记在 `'sys_metadata'` 哨兵下。改为读 `package_id`,与写路径、`getMetaItems`、以及相邻的非 object 分支一致。
+
+用户可见的行为差异:归属键同时就是包过滤键(`getAllObjects(packageId)`),所以此前一个对象在**创建时**出现在自己所属包的侧边栏过滤里,**重启之后就消失**;更要紧的是重启后的第一次编辑——boot 登记 `'sys_metadata'`、保存登记 `app.<slug>`,`registerObject` 抛 `already owned by package …` 被 `applyObjectRegistryMutation` 吞成 `console.warn`,保存回 `success: true` 而内存 schema 停在重启时的版本,这一笔编辑被静默丢弃(cloud#970 的重启面)。两侧统一到真实 id 后,过滤与编辑都跨重启成立。
+
+`@objectstack/objectql` 仅同步 `registry.ts` 中 `isTenantAuthored` 的契约注释:PR1 标注的「这半句描述的是契约,还不是代码」随本次落地摘除。

.github/workflows/lint.yml

@@ -717,6 +717,27 @@ jobs:
       - name: Check the decision frame is in sync across its four copies
         run: pnpm check:skill-frame-sync
 
+      # The third gate over SKILL.md, covering the one line the other two cannot see
+      # (#5331). check:skill-docs / check:skill-refs compare generated artifacts and
+      # check:skill-examples typechecks `os:check` blocks; none of them reads the
+      # `compatibility:` frontmatter line. That blind spot is measured, not theoretical:
+      # nine of ten skills declared `@objectstack/spec 16.x` for an entire major cycle
+      # while teaching 17's capabilities, with all three gates green throughout (#5245).
+      # #5245 corrected the values by hand; this reconciles them against
+      # packages/spec/package.json on every run so they cannot drift again.
+      #
+      # Note the contract is the wording that actually LANDED for #5245 — an exact
+      # `<major>.x` pin. If the wording is ever changed to an unpinned range, this gate
+      # goes RED rather than quietly matching nothing (#4690): a gate that cannot find
+      # its input must fail, never skip.
+      #
+      # Same job and same reasons as its neighbours: no paths filter and required, so it
+      # cannot go dormant on exactly the PR that breaks it — and a `skills/**` filter in
+      # particular would blind it to the other half of its input, packages/*/package.json,
+      # where a major bump is what makes the declarations stale in the first place.
+      - name: Check SKILL.md compatibility declarations match the workspace majors
+        run: pnpm check:skill-compatibility
+
       - name: Check the react-blocks contract is in sync with the spec
         run: pnpm --filter @objectstack/spec check:react-blocks
 

AGENTS.md

@@ -190,20 +190,87 @@ Even inside your own worktree, operate defensively:
    your working-tree change between the edit and the commit. On a real conflict,
    re-apply only *your* lines and let the PR merge integrate the rest.
 6. **Don't rebase or force-update shared branches** to tidy other agents' commits.
-7. **Merge only after remote CI is fully green. Never `gh pr merge --auto`.**
-   Auto-merge can land a still-red PR onto shared `main` and break it for every
-   parallel agent (see #1475). Merge serially; rebase other open branches before
-   merging the next one.
-   **Once the repo's merge queue is enabled, "add to queue" IS the sanctioned
-   path** — it is the opposite of the auto-merge this rule bans: the queue
-   builds your PR *as merged onto the current `main`* and lands it only if that
-   speculative result is green, which is exactly the §10 re-verification, done
-   by the platform, race-free. The manual serial protocol above is the fallback
-   for when the queue is unavailable. (Why this matters: `main` can land a PR
-   every few minutes at peak; a manual merge–reverify loop takes ~25 minutes,
-   so under load it *never* wins the race — one PR went three full green
-   cycles without managing to land. That is a livelock, not a discipline
-   failure.)
+7. **Land through the merge queue: arm auto-merge on a PR that is already
+   green, accepted and non-draft, then let the queue merge it.** Arming is how
+   you enter the queue, and the queue is what makes arming safe — it rebuilds
+   your PR *as merged onto the current `main`*, re-runs the subscribing
+   workflows on that rebuilt generation, and lands it only if the required ones
+   pass. That is the §10 re-verification, done by the platform, race-free.
+
+   **What "the queue validates" means here, measured** (`origin/main`,
+   2026-08-07): three of this repo's 22 workflows carry an `on: merge_group:`
+   trigger — `ci.yml`, `lint.yml`, `spec-liveness-check.yml` — and the Actions
+   API reports **2742** `merge_group` runs, the most recent 30 all on
+   `gh-readonly-queue/main/pr-<n>-<sha>` refs, all three workflows, all green.
+   A fourth workflow, `merge-queue-triage.yml`, is *not* a subscriber: it
+   watches those runs through `workflow_run` and comments the diagnosis on the
+   PR when a queue build goes red (#4859).
+
+   **This supersedes the older "never `gh pr merge --auto`" ban.** Its premise —
+   auto-merge lands a still-red PR on shared `main` (#1475) — is inverted by
+   rebuild-then-land, and the ban forbade what is now the sanctioned path. Its
+   *true half* survives, as a precondition rather than a prohibition: **arm only
+   what is already green and accepted**, where green means the gate-carrying
+   jobs' `conclusion` is `success`, not "no failure yet" — `in_progress` is not
+   a pass. Arming a red PR does not queue it, it hides it: #4852 sat armed from
+   10:15 for **100 minutes** without ever entering the queue, every poll
+   misreading "not on `main` yet" as "queued". So always read *two* things when
+   checking on a landing: the queue branch **and** `origin/main`.
+
+   **The queue enforces only the required set; everything else is advisory and
+   rides through.** #6067's final queue generation
+   (`gh-readonly-queue/main/pr-6067-db0d53c2…`) had `Lint & Type Check` at
+   `completed/failure` — run 31136745851, concluded 01:12:11Z — and merged at
+   01:13Z regardless; the `check:slot-lookup` red it carried then rode `main`'s
+   merge ref into every following PR's ESLint job until it was stanched (#6100,
+   the same shape as #5584 → #5601 → hot-fix #5615). Governance half: **#5617**,
+   under which the maintainer on 2026-08-07 added **ESLint** and **TypeScript
+   Type Check** to both `main`'s required-status-check set and the queue's check
+   set, so those two now block — the audit archived on that issue also lists
+   which other jobs can and cannot safely join them. A gate outside that set
+   stops nothing, which is why "arm only on green" is a rule and not a
+   formality.
+
+   **Three re-arm situations this repo has actually hit.** None of them is a
+   reason to avoid the queue; all are reasons to confirm a PR is still *in* it:
+   - **A red queue build ejects your entry and drops the auto-merge.** The
+     failure is often in a package your PR never touched, because the queue runs
+     the *full* suite while the PR ran affected-only. #6059 was ejected at
+     01:03:02Z on a known flaky (`datasource-pool-support.test.ts`, #6044),
+     diagnosed against the triage comment, re-armed at 01:04:15Z and landed at
+     01:25:00Z. Recognise the signature first, then re-arm once — never re-queue
+     reflexively.
+   - **Collateral eviction is silent by design.** `merge-queue-triage.yml`
+     comments only on `conclusion == failure`; an entry cancelled because
+     something *ahead* of it failed gets nothing, since that outcome says
+     nothing about your PR. A PR that is neither on `main` nor in the queue was
+     dropped — re-arm it.
+   - **Flipping back to draft drops auto-merge and queue membership at once, and
+     neither returns by itself.** The order is therefore fixed: ready *first*,
+     arm *second*. (This one is the repo's standing operating note —
+     `.claude/skills/pm-dispatch/SKILL.md` note 1 — not an API measurement.)
+
+   And one non-fix: **a stale red does not clear by re-running.**
+   `rerun_failed_jobs` reuses the original run's commit and merge ref, so it
+   cannot see a fix that landed on `main` since. Compare the fix's merge time
+   against the run's creation time; if the fix is later, only a new commit
+   (`git merge origin/main`) helps — #4852's red was byte-identical across a
+   rerun until #4856 landed.
+
+   **Not measured here:** whether a direct, non-auto `gh pr merge` is refused
+   with `405 Changes must be made through the merge queue`. Establishing that
+   would mean actually attempting a merge on a live PR, which is not an
+   experiment worth running. objectui returns 405; that is **not** extrapolated
+   to this repo (objectui#3243) — separate rulesets, and #5617's cross-repo
+   audit found the two configured differently.
+
+   **Fallback, when the queue is unavailable:** the old manual protocol — merge
+   serially, only after remote CI is fully green, rebasing other open branches
+   before merging the next one. It is a fallback because it loses under load:
+   `main` can land a PR every few minutes at peak while a manual merge–reverify
+   loop takes ~25 minutes, so one PR went three full green cycles without
+   managing to land. That is a livelock, not a discipline failure — and it is
+   why the queue is the default path rather than an optimisation.
 8. **Testing needs a server? Start your own temporary one — never stop someone
    else's.** A running dev server you didn't start probably belongs to another
    agent or the user; killing it (or its port) breaks their in-flight work. Spin
@@ -253,8 +320,9 @@ Even inside your own worktree, operate defensively:
    - **Full `pnpm typecheck && pnpm test` again only when** the incoming
      commits touch the same packages or the same behavior your diff does, or a
      conflict occurred outside trivially-mechanical files.
-   - CI on the PR (and the merge queue, once enabled) validates the merge
-     commit itself — that second CI round is where joint breakage surfaces, and
+   - CI on the PR, and then the merge queue on its rebuilt generation (§7),
+     validates the merge commit itself — that second CI round is where joint
+     breakage surfaces, and
      the guards in `scripts/check-*.mjs` exist largely because this class of
      breakage is invisible to `git merge`.
 11. **Generated artifacts don't text-merge — a driver defers them and
@@ -765,10 +833,10 @@ it to `OPEN_CAPABILITY_REGISTRIES` in the same PR that fixes it.
 
 1. `pnpm test` — verify nothing broke. Touched a type-check-covered package? `pnpm typecheck` too.
 2. **Land it — don't leave passing work in the working tree.** Once tests pass,
-   create a feature branch, commit, push, open a PR, and merge it after remote
-   CI is fully green (see Multi-agent discipline: never straight to `main`,
-   never `gh pr merge --auto`). A finished task = a merged PR, not a dirty
-   working tree.
+   create a feature branch, commit, push, open a PR, and — once remote CI is
+   fully green and the PR is accepted — arm auto-merge so the queue lands it
+   (Multi-agent discipline §7: never straight to `main`; never arm a PR that
+   isn't green yet). A finished task = a merged PR, not a dirty working tree.
 3. **Add a changeset for feature work.** When the change is a feature or functional improvement, run `pnpm changeset` (or add a `.changeset/*.md` entry) describing it before committing. Pure bug fixes do **not** require a changeset.
    **Breaking changesets must carry their migration.** If the change removes or renames anything an author can write (a spec key, an export, a config field), the changeset body must state the FROM → TO mapping and the one-line fix — this text ships to consumers as `CHANGELOG.md` inside the npm package and is what an upgrading agent greps after the tombstone error. Removing an authorable spec key also requires a tombstone so the rejection itself carries the prescription — `retiredKey()` (`packages/spec/src/shared/retired-key.ts`) on a non-strict schema, or an entry in the relevant `UNKNOWN_KEY_GUIDANCE` / `*_RETIRED_KEY_GUIDANCE` map (see `object.zod.ts`, `ai/tool.zod.ts`) when the schema is `.strict()`. The changeset is one of fourteen surfaces a retirement touches — follow the `spec-property-retirement` skill (`.claude/skills/`) rather than reconstructing the kit, and note the two routes imply **opposite** liveness-ledger dispositions.
 4. **Added or removed a `packages/spec` export? Run `pnpm --filter @objectstack/spec gen:api-surface` and commit the result.** The `TypeScript Type Check` job diffs spec's built export surface against `api-surface/` (one shard per entry point since #5837); a new export makes the snapshot stale and turns the job red. It reads the **built `dist` declarations**, so `OS_SKIP_DTS=1` — the flag you reach for to make local builds fast — skips exactly the artifact the gate inspects, and the check passes locally while failing in CI. Same shape for the other generated-artifact gates in that job (`check:docs`, `check:skill-refs`, `check:react-blocks`), which read `src/` and so do reproduce locally.

content/docs/references/ai/conversation.mdx

@@ -8,7 +8,6 @@ description: Conversation protocol schemas
 AI Conversation Memory Protocol
 
 Multi-turn AI conversations with token budget management.
-
 Enables context preservation, conversation history, and token optimization.
 
 <Callout type="info">

content/docs/references/ai/embedding.mdx

@@ -10,25 +10,17 @@ Embedding & Vector Store Primitives
 Platform contract for configuring embedding models and vector stores.
 
 Scope (intentionally minimal):
-
 - How to reference an embedding model (provider + model name + secret).
-
 - How to reference a vector store (provider + connection).
 
 NOT in scope (these belong to application code, not the platform):
-
 - Chunking strategies (fixed/semantic/recursive/markdown).
-
 - Retrieval pipelines (rerankers, multi-stage retrieval, filters).
-
 - Document loaders / ingestion DSLs.
-
 - End-to-end RAG pipeline orchestration.
 
 These were removed in v1 because they describe one specific way to
-
 build a RAG application; the platform's job is to expose the embed +
-
 vector primitives so any RAG strategy can be built on top.
 
 <Callout type="info">

content/docs/references/ai/knowledge-document.mdx

@@ -6,15 +6,11 @@ description: Knowledge Document protocol schemas
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
 Knowledge Document / Chunk / Hit — canonical shapes shared by every
-
 `IKnowledgeAdapter` implementation.
 
 The framework does **not** prescribe chunk strategy or vector
-
 format. Adapters are free to chunk however they like; the framework
-
 only requires they round-trip these shapes when talking to the
-
 `IKnowledgeService`.
 
 See `content/docs/protocol/knowledge.mdx` for the full design.

content/docs/references/ai/knowledge-source.mdx

@@ -6,17 +6,12 @@ description: Knowledge Source protocol schemas
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
 Knowledge Source — declarative metadata describing what to index and
-
 which adapter to use.
 
 A KnowledgeSource is the metadata-level equivalent of an
-
 `IDataEngine` driver binding: it pairs a logical source description
-
 (object/file/http) with the *id* of an `IKnowledgeAdapter` plugin
-
 that will actually do the work. The adapter resolves the id at
-
 runtime via `IKnowledgeService.registerAdapter`.
 
 See `content/docs/protocol/knowledge.mdx` for the full design.