fix(cloud-connection): the install-local listing marks a package the rehydrate refused as not loaded (#21822)

[objectstack-fleet]

Fixes #21822

Clause-②: no

What changed

After a restart whose kernel:ready rehydrate refused a protocol-incompatible package (ADR-0087 D1), GET /api/v1/marketplace/install-local listed it like any loaded package, and each GET logged a warn that it could not read the package's seed rows. Now the rehydrate records each entry it refuses, and the listing serves that entry with a notLoaded marker carrying the refusal's code and the declared range. The listing reads no seed rows for it, so the per-request warn is gone. This is the direction triage ruled (5988934231): a marker, not omission.

packages/cloud-connection/src/marketplace-install-local-plugin.ts only. ⛔ No change to the refusal itself (its line, level and wording), to DELETE, to the install route or to handleReseed. No packages/spec path.

The wire shape (for objectstack-ai/objectui#11645 to render)

A refused entry, as an operator (manage_metadata) reads it:

{
  "packageId": "com.example.crm",
  "versionId": "…",
  "manifestId": "com.example.crm",
  "version": "…",
  "installedAt": "…",
  "notLoaded": { "code": "OS_PROTOCOL_INCOMPATIBLE", "requiredRange": "^16" },
  "installedBy": "…"
}

• notLoaded is CLOSED: exactly code and requiredRange, the handshake diagnostic's own member names (the same requiredRange the install door's 422 carries in error.details). It is not a spread of the diagnostic.
• notLoaded stands in place of withSampleData. The listing does not read the package's rows, so it makes no claim about them: the key is omitted, not false. This follows the same rule as installedBy for a narrowed caller.
• A narrowed caller (authenticated, no manage_metadata) gets the same item without installedBy. The marker is served to every authenticated caller.
• A loaded entry is byte-identical to before: withSampleData, no notLoaded key. total counts marked entries.
• After DELETE the entry is gone from the ledger and the listing. Once a compatible version is installed over it, the entry is listed as loaded, with no marker.

Where "not loaded" comes from (H3, measured on the code)

I compared two sources:

• A, the rehydrate's own record of what it refused.
• B, re-running checkProtocolCompat on each ledger entry per request.

I chose A. It records what the rehydrate did, so it agrees with it by construction. B is a second judgement, and it disagrees with what happened in reachable states:

• rehydrate returns before the handshake loop when there is no manifest service ("no manifest service — rehydrate skipped"). B would mark entries whose refusal never happened.
• The listing re-reads the ledger directory on every request. The rehydrate's own comment names a ledger shared with "a runtime of another protocol", so an entry written there after this boot was never judged here, and B would report a refusal this runtime never made.

The record is keyed by manifest id and holds the refused entry's installedAt, which says which entry was refused. The install door is the only writer of a new entry, it always stamps a fresh installedAt, and it runs the same handshake first, so it can never write an incompatible entry. So a compatible re-install stops the marker without any write to the record from the install door or from DELETE. rehydrate clears the record when it starts.

Pins (the ruling's, verbatim, plus the order's addition)

• "after a restart whose rehydrate refused an entry, GET /install-local lists it with the marker and the code."
• "A loadable entry is unchanged, and DELETE on the marked entry still works."
• No seed-row read and no withSampleData warn for the marked entry.

Unit (src/marketplace-install-local-listing-not-loaded.test.ts, 7 cases): a fresh plugin over a ledger with one refused and one loadable entry. The engine double answers only for registered objects, the way the real one answers Object '…' not found. The cases cover:

• the marker, on the operator's item and the narrowed caller's;
• the closed member set;
• zero reads of the marked package's object and zero seed-row warnings, with a lit control that the loadable entry's object was read;
• the loadable item, byte-equal to the one a ledger without the refused entry serves;
• DELETE;
• a compatible re-install clears the marker.

Door (packages/qa/dogfood/test/install-local-listing-not-loaded.dogfood.test.ts, 7 cases): real showcase boots over one databaseFile and one ledger.

• Boot 1 installs the CRM package (28 seed rows) and a small loadable package.
• Between the boots, the CRM ledger entry is rewritten to declare ^(major-1), an install made for an older runtime.
• Boot 2's rehydrate refuses it; the capture holds the error line.
• The GET serves the marker. The loadable item is byte-identical to its boot-1 item. DELETE answers 200, and the listing then holds the loadable package alone.
• The no-warning assertion has a lit control: an unreadable ledger file planted before boot 2 makes the same GET log its own warn through the same logger, in the same capture window.

Reverse verification (one-off, not kept)

The plugin file was restored to the merge base (c4d57131, blob 50a71c2f) with a trap that restores HEAD. Each leg was proven on disk: the refusedAtRehydrate count went 6 → 0 → 6, the hash equalled the BASE blob, then the HEAD blob 411ad7a9, and git diff HEAD came back empty. Both suites import the plugin from src: the unit test by a relative path, and the dogfood isolated project aliases @objectstack/cloud-connection to ../../cloud-connection/src/index.ts. So no dist leg applies.

• Unit, pre-fix: 3 failed | 4 passed (7). The marker cases fail, and the read/warn case shows both facts: readsOfMarkedEntry: ["qa_old_account"] and the warning com.example.qaold21822: the installed-apps listing could not read this package's seed rows (qa_old_account: Object 'qa_old_account' not found), so it answers withSampleData: false for it. With the fix: 7 passed.
• Door, pre-fix: 2 failed | 5 passed (7). notLoaded is undefined, and the GET logs WARN [MarketplaceInstallLocal] com.example.crm: the installed-apps listing could not read this package's seed rows (crm_account: Object 'crm_account' not found; crm_contact: …; crm_opportunity: …; crm_lead: …; crm_activity: …). This is the card's own reading, reproduced. With the fix: 7 passed.

The preservation pins (the loadable entry, DELETE, the compatible re-install, the preconditions and the capture control) pass on both sides, as preservation pins should.

Tests and gates

All readings are from claude/issue-21822-listing-not-loaded-marker after one merge of origin/main (07bf21ff). Final head: 36817931.

• Build: the @objectstack/cloud-connection and @objectstack/dogfood dependency closures, rebuilt after the merge: turbo run build, 63/63 tasks.
• pnpm --filter @objectstack/cloud-connection test: 40 files / 492 tests passed (at 6bb9f960). The one later commit, 36817931, changes only the new test's engine double, and that file was re-run at 36817931: 7/7.
• pnpm --filter @objectstack/cloud-connection typecheck: exit 0. tsc --listFiles includes the new test file.
• pnpm --filter @objectstack/dogfood typecheck: exit 0. tsc --listFiles includes the new dogfood file.
• Dogfood, narrowed: vitest run --project isolated over install-local-listing-not-loaded, install-local-listing-sample-data, install-local-purge-sample-data and install-local-no-active-organization: 4 files / 27 tests passed. This narrowing is proven, not assumed: git grep -l -E 'MarketplaceInstallLocalPlugin|marketplace/install-local' -- packages/qa/dogfood/test at HEAD names exactly these four files. The rest of the suite belongs to CI's Dogfood Regression Gate.
• Gate battery: the 67 commands dispatch-gates --commands derives for this change set (the dispatch's 49 plus 18 more), all exit 0 at 36817931. dispatch-gates --ran: "67 derived, 67 run, 0 NOT-MEASURED, 0 UNRUN".
  • check:dual-build-cjs-loads first answered PREREQUISITE NOT MET: eight packages outside this closure had no dist. They were built and the gate re-ran green: "106 published require entry point(s) across 66 package(s) load".
  • check:where-matcher caught the new engine double reading a combinator as a field name. The double now refuses what it does not implement: 461/461 conforming.
• pnpm lint (eslint . --no-inline-config, the whole repository): exit 0 at 36817931.
• Stale-tree note: after the one merge, origin/main gained 088428fb (fix(runtime): PATCH reaches a declared AI route through the /ai/* wildcards, and an undeclared method answers 405 #21823: the runtime dispatcher and scripts/check-route-envelope.mjs). So check:route-envelope ran on its pre-fix(runtime): PATCH reaches a declared AI route through the /ai/* wildcards, and an undeclared method answers 405 #21823 copy. CI runs on the merge ref.

Acceptance notes

• Other not-loaded states stay unmarked; they are outside this ruling, which names the protocol refusal. None was measured through a public door, and none is filed.
  • A rehydrate whose register throws ("rehydrate failed for …", at error) is still listed with withSampleData, and gets the per-request seed-row warning.
  • A cloud-snapshot install whose hot-register failed ("will load on next restart") answers 200 and is listed as installed until the restart.
  • No manifest service at kernel:ready ("rehydrate skipped") lists every entry as installed.
  • If a second not-loaded cause is ever marked, notLoaded.code is its slot. Today the shape is closed to the one code.
• Not measured here: reseed and purge on a marked entry. console(marketplace): Installed Apps shows a package the runtime refused to load as installed — render the listing's not-loaded marker (the console half of objectstack-ai/objectstack#21822) objectui#11645 already says Details offers no action that needs a loaded package.
• Release text: the pending [finding] install-local: the listing's withSampleData is install-wide, so after a purge in organization A, GET /install-local read as organization B answers withSampleData: false while B still holds its 28 seed rows #21775 changeset's "(for example, a package the runtime did not load)" stays true, for the first case above.
• The refusal line is unchanged: same level (error), same wording. Only its docblock now says the listing marks the entry.
• Concurrency: [finding] install-local: reseed-sample-data over intact sample rows answers 422 RESEED_NO_ROWS "The package declares no seedable records for this runtime" while the package declares 28 records (all already present) #21776's dev edits handleReseed in the same file. This PR touches only the rehydrate's refusal branch, the record field, handleList and a helper after it, so there is no overlapping region.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cloud-connection, touching 10 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/deployment/cli.mdx (via MarketplaceInstallLocalPlugin (symbol, a top-level class))

⛔ 3 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v12.mdx (via OS_PROTOCOL_INCOMPATIBLE (literal, a string literal in a comment in MarketplaceInstallLocalPlugin))
• content/docs/releases/v15.mdx (via OS_PROTOCOL_INCOMPATIBLE (literal, a string literal in a comment in MarketplaceInstallLocalPlugin))
• content/docs/releases/v17/17-5.mdx (via OS_PROTOCOL_INCOMPATIBLE (literal, a string literal in a comment in MarketplaceInstallLocalPlugin))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 3 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 6fb71152ca5cc7c71723f15eaf33bb3f8f7138e8 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 15ef59c9dc4fa3cc5c4ad1225043cda837a52392 — the merge of head 3681793122c73909ef9bdb707e78b44fd16f3ede into base 6fb71152ca5cc7c71723f15eaf33bb3f8f7138e8, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 15ef59c9dc4fa3cc5c4ad1225043cda837a52392 && git checkout 15ef59c9dc4fa3cc5c4ad1225043cda837a52392
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 6fb71152ca5cc7c71723f15eaf33bb3f8f7138e8 3681793122c73909ef9bdb707e78b44fd16f3ede && git checkout -B drift-repro 6fb71152ca5cc7c71723f15eaf33bb3f8f7138e8 && git merge --no-ff 3681793122c73909ef9bdb707e78b44fd16f3ede

node scripts/docs-audit/affected-docs.mjs --json 6fb71152ca5cc7c71723f15eaf33bb3f8f7138e8

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 6fb71152ca5cc7c71723f15eaf33bb3f8f7138e8 → pass the list as
args.docs, on the commit named under Which tree this was computed on.