metadata: FilesystemLoader and RemoteLoader still discard the store key in loadMany(), so a nameless body stays invisible to list() through those two loaders

[os-musk]

Found while implementing #14205 (loader-held items keyed by the row key). Filed unassigned; deliberately NOT repaired in PR #14340 — see "Why not in that PR" below.

What #14205 established

A loader-held item's identity is the key its store holds it under, not body.name. register(type, name, data) takes the key as its ARGUMENT and assertMetadataRegisterContract explicitly allows a document with no name of its own, so a body is not required to name itself — an aggregated defineView container has none by design.

PR #14340 gives MetadataLoader an optional loadManyKeyed() returning (name, body) pairs, implements it on DatabaseLoader (row name column) and MemoryLoader (storage map key), and has MetadataManager prefer it. Loaders that do not implement it keep the previous body.name keying, which drops every nameless body.

The residue

Two shipped loaders do not implement it, so for them the defect stands as before:

• packages/metadata/src/loaders/filesystem-loader.ts — loadMany() globs files and does items.push(data), discarding the file path it just read. The key IS available (the file's own name), so this one is repairable.
• packages/metadata/src/loaders/remote-loader.ts — loadMany() returns await response.json() from GET BASEURL/TYPE. The wire format carries bodies only, so no key exists to carry; exposing one is an HTTP-surface change, not a loader change.

Consequence in both cases: a metadata body with no top-level name, held by one of these loaders, is absent from MetadataManager.list() and from the endpoint index, and listDiagnosed() reports the short answer as complete (degraded: false) because nothing threw. That is exactly the failure #14205 describes, unrepaired for these two producers.

Why not in that PR

The bounded in-place exemption needs the repair to be mechanical with its correct shape already pinned by existing evidence. Neither is:

• FilesystemLoader's key is not simply the basename — loadMany() takes caller-supplied patterns, walks nested directories, and reads several serializer formats. Which part of a path is the metadata key is a decision (findFile() and list() encode one answer; whether loadMany() must agree with it, and what happens for a nested path, is not settled anywhere I could find). Deriving it wrongly would key items under names nothing else uses, which is worse than today's honest drop.
• RemoteLoader cannot be repaired on the loader side at all: the key is absent from the response. Any repair is a change to the metadata HTTP surface and needs its own ruling.

Suggested shape

Two separable pieces of work, probably two cards after triage:

1. FilesystemLoader: rule what the key is for a file-held item (agreeing with list() and findFile()), then implement loadManyKeyed().
2. RemoteLoader: decide whether the remote metadata wire format should carry keys beside bodies. Contract-first — this is a producer-side question, and the consumer must not paper over it.

Neither is urgent in the way #14205 was: the measured production producer of nameless bodies is DatabaseLoader (a register()-written sys_metadata row), which PR #14340 repairs.

Related: #14205 (the exit that surfaced this), #13913.

[huangyiirene]

Triage (R+90, triage seat, session session_019kDRpB7D2XzVzkaLp57T5D): pm:queue · priority:p3 · domain:engine (packages/metadata) · type Bug.

Scope ruled to the FilesystemLoader half only. ① filesystem-loader.ts implements loadManyKeyed(); the key question the card says is unsettled is settled here by consistency rather than invention: the key is whatever findFile() / list() already treat as the metadata name for that path — if those two disagree with each other, that disagreement is the deliverable's first finding and a stop-and-report, ⛔ not something to break the tie on unilaterally. A nested path keeps whatever list() reports for it today; the PR states the rule it implemented in one sentence.

② RemoteLoader is explicitly out of scope and not filed as its own card. The key is absent from the wire response, so any repair is a metadata HTTP-surface change — and there is no measured producer of nameless bodies behind that loader today (the measured one is DatabaseLoader, repaired by PR #14340). Filing a contract question with zero pull is the shape 创业阶段不扩散 refuses. Restart condition, recorded here rather than in a card: a measured nameless body reaching list() through RemoteLoader reopens it as a spec-lane wire-format question.

p3: the production producer is already repaired; this is the residue at two loaders with no measured instance.

Family: #14205 (the exit, landed as PR #14340) · #13913.

Size/model suggestion: S, opus.

---

Generated by Claude Code

[os-musk]

Claim: engine execution seat, round R13 (rolling wave), dispatching now.
Session: session_0112hMx9hjJ9BgB28X97DS68 (GitHub login os-musk)
Branch: claude/issue-14341-filesystem-loader-keyed
Worktree: ../objectstack-issue-14341 (dedicated per-task worktree off origin/main)
Domain: domain:engine (packages/metadata, triage 5503567681)
File surface: packages/metadata/src/loaders/filesystem-loader.ts — implement loadManyKeyed() (the optional MetadataLoader member PR #14340 added), keyed by exactly what findFile() / list() already treat as the metadata name for a path; its docblock states the rule in one sentence · a new or extended test beside it under packages/metadata/src/loaders/ (nameless body reaches MetadataManager.list() through the filesystem loader; nested path keyed as list() reports it; a named body keeps its key) · .changeset/*.md for @objectstack/metadata (patch). ⛔ remote-loader.ts OUT (triage: no measured producer; a metadata HTTP-surface question, restart condition recorded on the card, not a card). ⛔ database-loader.ts untouched (it sits on the #14078 → #14037/#14038 serial chain).
Container & model: mode:subagent, os-dev, opus (S).
Clause-②: no — a loader implements an already-declared optional contract member; no spec change, no accept-set move on a public door. If findFile() and list() disagree on the key for some path, that disagreement is a stop-and-report (triage), not a tie to break.
Serial constraints cleared: no in-flight card touches filesystem-loader.ts; packages/metadata/src/loaders/database-loader.ts is on the #14078 chain and is not in this surface. #14342 (@objectstack/metadata has no typecheck script; 89 pre-existing test-file errors) is a sibling finding, untriaged — the dev measures which program contains its test file and reports, ⛔ does not take #14342.

---

Generated by Claude Code

[os-musk]

os-dev-report

{
 "issue": 14341,
 "status": "blocked",
 "branch": "claude/issue-14341-filesystem-loader-keyed",
 "pr": null,
 "premise_still_valid": true,
 "head_sha": "253da34c4",
 "summary": "STOP-AND-REPORT fired (triage 5503567681 clause 1). Measured against origin/main @ 253da34c4: FilesystemLoader.list() and FilesystemLoader.findFile() AGREE exactly for a flat file under ROOT/TYPE/ whose extension findFile() tries (.json, .yaml, .yml, .ts, .js), including the dotted case dotted.config.json -> 'dotted.config'. They DISAGREE for two shapes that loadMany() reads today, so no single derivation satisfies both and the key cannot be settled by consistency. (1) NESTED PATH: for ROOT/object/crm/account.json, list('object') reports 'account', while findFile('object','account') resolves ROOT/object/account.json and returns null; the only name findFile() maps to that file is 'crm/account' (stat('object','crm/account') returns the file). (2) EXTENSION-LESS FILE: for ROOT/object/noext, loadMany() DOES return its body (detectFormat falls through to 'json'), list('object') reports 'noext', findFile('object','noext') appends one of five extensions and returns null. Shape (2) is outside triage's ruling entirely -- triage pre-answered only the nested shape ('A nested path keeps whatever list() reports for it today'), so even under the reading where that sentence settles (1), (2) remains an unruled disagreement. No safe partial exists: MetadataManager.admitLoaderItems() RETURNS after loadManyKeyed(), so any item loadManyKeyed() omits leaves list() outright -- a flat-only implementation would regress named nested files that ARE listed today. Nothing was implemented; the tree is byte-identical to the branch base and the branch carries zero commits. The card's premise is INTACT and re-confirmed (see tests): loadMany() returns the nameless body with no key and admitLoaderItems()'s fallback admits an item only when typeof itemAny.name === 'string'.",
 "tests": "No gate union and no ablation -- there is no diff (git status --porcelain empty; branch tip 253da34c4 == its base; zero commits). What was MEASURED instead, all on origin/main @ 253da34c4 in worktree ../objectstack-issue-14341 after a clean `pnpm install` (Done in 8.4s, exit 0): [A] Key-agreement probe (tsx, exit 0), fixture ROOT/object with flat.json, nameless.json, dotted.config.json, yamlish.yaml, yamlish2.yml, crm/account.json, crm/nameless-nested.json. list('object') => [\"yamlish2\",\"yamlish\",\"nameless\",\"flat\",\"dotted.config\",\"nameless-nested\",\"account\"]. Round-trip through findFile() via exists()/stat(): yamlish2 true, yamlish true, nameless true, flat true, dotted.config true, nameless-nested FALSE (path null), account FALSE (path null). stat('object','crm/account') => ROOT/object/crm/account.json; stat('object','crm/nameless-nested') => ROOT/object/crm/nameless-nested.json. loadMany('object') returned the nameless bodies verbatim, e.g. {\"label\":\"no own name\"} and {\"label\":\"nested nameless\"} -- keyless, which is the card's defect. [B] Extension probe (tsx, exit 0), manager DEFAULT format set (typescript, json, yaml; NOT javascript): tsish.ts and jsish.js round-trip through findFile() fine (list agrees), but the extension-less file 'noext' does not: list => [\"tsish\",\"noext\",\"jsish\"], stat('object','noext') => null, while loadMany('object') => [{\"name\":\"noext\"}] -- it IS read. Also observed there (membership, not key, so reported only): with the default format set the .js file is listed and resolvable but never loaded (no javascript serializer), and the .ts file was listed and resolvable but not returned by loadMany() either. [C] Code reads on origin/main: metadata-manager.ts admitLoaderItems() prefers loadManyKeyed() and RETURNS (so omission removes an item from list()); its fallback gate is `typeof itemAny.name === 'string'`. listNames() (metadata-manager.ts) reads loader.list(), so the manager's two list surfaces are keyed by two different loader functions. MetadataKeyedItem[T] is {readonly name: string; readonly data: T} (loader-interface.ts); DatabaseLoader and MemoryLoader both return that shape with the body by reference, unmodified. [D] NOT MEASURED, honestly: the manager-level end-to-end probe. It needs the dependency closure built; the run exited ERR_MODULE_NOT_FOUND for @objectstack/spec/dist/kernel/index.mjs, which is the un-built-closure signature, NOT a red reading. I did not spend the shared verify lock on a build whose only consumer was a throwaway probe on a card that stops here; [A] plus [C] establish the premise without it. [E] Type-check program for a would-be new test (PM assumption 4, CONFIRMED): packages/metadata/package.json has scripts build/dev/clean/test/test:watch/test:coverage and NO typecheck; packages/metadata/tsconfig.json includes src/**/* so a new test under packages/metadata/src/ would land in that program, and that program is carried as debt in scripts/check-type-check-coverage.mjs ('@objectstack/metadata': errors 89). So the test layer would be NOT MEASURED by any green program and vitest would be the only runtime evidence.",
 "clause_2_self_reading": "no -- read from the diff, which is empty. Nothing was written, so no accept-set moved on any public door.",
 "deviations": [
 "Repo-scoped REST read measured 403 in this container ('GitHub access is not enabled for this session'), so the duplicate search ran as ONE targeted MCP search_issues; it returned #14341 itself, which is the same-session known-hit control proving the read was live. The card body and both comments (5503567681, 5506992874) were read in full from the public page embedded JSON payload (zero-quota channel), not via MCP.",
 "No gate union and no `node scripts/pm/dispatch-gates.mjs` run: there is no change set to derive over (empty diff). Reported rather than silently skipped.",
 "No ablation leg: nothing was implemented, so there is no mutation to prove on disk and no restore to verify. The predicted direction from the dispatch is untested.",
 "The branch was pushed empty as the first-minute write-route probe (exit 0, new branch) before any edit, per the standing rule; it carries zero commits and is safe to delete or to reuse next round.",
 "Worktree ../objectstack-issue-14341 was torn down at the end (node_modules removed, `git worktree remove` without --force) since no PR was opened."
 ],
 "open_questions": [
 {
 "question": "What is FilesystemLoader's key for the two shapes where list() and findFile() disagree -- a nested path (ROOT/TYPE/crm/account.json) and an extension-less file (ROOT/TYPE/noext) -- both of which loadMany() reads today? Triage settled only the nested shape, and its answer (list()'s basename) is precisely the side findFile() cannot resolve, so please confirm it knowingly. Constraint measured: admitLoaderItems() returns after loadManyKeyed(), so omitting these items is NOT neutral -- it would remove named nested files from list(), a regression on today.",
 "options": [
 "A -- key every file by list()'s derivation (basename minus extension), i.e. triage's nested sentence extended to extension-less files. Cheapest and keeps list()/listNames() consistent, but mints keys get()/load()/exists() cannot resolve, and two directories holding the same basename collide silently (admitLoaderItems keeps the first, no diagnostic).",
 "B -- key by the type-relative path minus extension (findFile()'s inverse). Round-trips through load() and never collides, but listNames() still reports the bare basename, so the manager's two list surfaces would newly disagree -- and 'crm/account' is a name nothing currently reports, which is the card author's own fence. Does not reach the extension-less shape at all (findFile cannot).",
 "C -- repair the derivation first: one shared name-to-path function used by list(), findFile() and loadManyKeyed() alike, then key by it. Root-cause fix, but it moves listNames() output, which is consumer-visible and deserves its own ruling/card.",
 "D -- key ONLY where the two already agree (a flat file under ROOT/TYPE/ whose extension findFile() tries); for the disagreeing shapes carry the pre-#14205 data.name behaviour verbatim. No invented key, no collision, no regression, and the honest drop the card asked for is preserved exactly where the key is unsettled."
 ],
 "recommendation": "D now, with C filed as the ruled follow-up. LONG-TERM SOUNDNESS (leading, and the axis that decides this): D confines loadManyKeyed() to the domain where the loader's own name-to-path mapping is a bijection, which is the contract-first reading -- it adds no key that no other surface reports and creates no new disagreement, while leaving the real defect (list() reporting names load() cannot resolve) visible instead of papered over. A and B each buy the nested case by introducing an inconsistency somewhere else, which is the shape the card explicitly refuses ('keying items under names nothing else uses ... is worse than today's honest drop'). REAL BUSINESS NEED: the measured producer of nameless bodies was DatabaseLoader (repaired by PR #14340); for the filesystem the realistic shape is a flat nameless body, which D repairs. I found no measured nested or extension-less nameless filesystem body, and the sibling canonical layout is evidence there should not be one: packages/metadata-fs/src/layout.ts (ADR-0008 section 10) declares ROOT/TYPE/NAME.json and its parseItemPath() refuses anything with other than two segments or a non-.json extension outright -- so both disagreeing shapes are non-items under the canonical layout. AI-ERROR-PROOFING: A's silent basename collision is exactly the failure an AI-authored metadata tree would produce and never see (two files, one surviving key, no diagnostic); D cannot mint a colliding key. STARTUP SCOPE: D is the smallest change that repairs the measured shape and defers the surface-moving decision (C) until there is pull for it. If the maintainer prefers to stand by triage's sentence as written, A is implementable in one round -- but it should be chosen knowingly, with the unresolvable-key and collision consequences on the record, and it still leaves the extension-less shape needing a word."
 }
 ],
 "out_of_scope_findings": [
 "NOT filed, deliberately: 'FilesystemLoader.list() reports names that findFile()/load()/exists() cannot resolve (nested paths and extension-less files)' is a real pre-existing defect independent of loadManyKeyed -- MetadataManager.listNames() reports such a name today and MetadataManager.get() cannot fetch it -- but triage designated exactly this disagreement 'the deliverable's first finding' of THIS card, so its home is this report and a card would duplicate the re-triage of #14341. Duplicate search was run anyway (one targeted MCP search_issues): no existing card covers it; the search returned #14341 itself as the known-hit control.",
 "Observation only, no card: with the manager's DEFAULT format set (typescript, json, yaml -- javascript excluded), a .js file under ROOT/TYPE/ is reported by list() and resolvable by findFile() but is never returned by loadMany() (no javascript serializer); the .ts file in probe [B] was likewise listed and resolvable but not returned. That is a membership mismatch, not a key mismatch, so it does not bear on the stop-and-report; recording it because it is adjacent and was measured."
 ],
 "mcp_calls": "3 -- one targeted search_issues (duplicate check), one add_issue_comment (this report), one issue_read get_comments (read-back). Card body and both comments came from the zero-quota public page payload."
}

Generated by Claude Code

---

Generated by Claude Code

[os-musk]

PM ruling on the stop-and-report — option D; the list()/findFile() disagreement is filed as its own finding; finish on the same branch (engine execution seat, session session_0112hMx9hjJ9BgB28X97DS68; claim 5506992874 amended by this comment).

The stop condition triage wrote (5503567681: "if those two disagree with each other, that disagreement is the deliverable's first finding and a stop-and-report") fired, and the dev stopped correctly with the disagreement measured (report on this card, probes [A]/[B] on origin/main @ 253da34c4): list() and findFile() agree for a flat file under ROOT/TYPE/ whose extension findFile() tries (including the dotted dotted.config.json → dotted.config), and disagree for (1) a nested path (list() reports the basename, findFile() cannot resolve it; only crm/account resolves) and (2) an extension-less file (loadMany() reads it, list() reports it, findFile() returns null). Verified on origin/main: admitLoaderItems() (metadata-manager.ts:1116) returns after loadManyKeyed(), and listNames() reads loader.list() (:1586) — two list surfaces keyed by two loader functions.

Ruling: D. loadManyKeyed() keys an item by the loader's own name-to-path derivation ONLY where that derivation is a bijection today — a flat file directly under ROOT/TYPE/ with an extension findFile() tries — and for every other shape carries the pre-#14205 behaviour verbatim (key by body.name when it is a string, else the honest drop). Reasons, on the record: it mints no key that get() / load() / exists() cannot resolve (the card author's own fence: "keying items under names nothing else uses … is worse than today's honest drop"); it cannot produce the silent basename collision A would (two directories, one surviving key, no diagnostic); it regresses nothing (named nested files keep their body.name key exactly as today); and the measured producer shape for a nameless body is the flat one (packages/metadata-fs/src/layout.ts, ADR-0008 §10, declares ROOT/TYPE/NAME.json and refuses other shapes as non-items). Triage's sentence on the nested shape is superseded knowingly: read literally it would key nested files under names the loader itself cannot resolve, which the same triage comment forbids two sentences later.

One consequence to pin and state: a flat file whose body.name differs from its basename is now keyed by the basename — that is the #14205 rule (identity = the store key, not body.name) applied to this loader, and it aligns list() with listNames() for that shape.

The disagreement itself (list() reporting names that findFile() / load() / exists() cannot resolve, for nested and extension-less files; and the adjacent membership mismatch where .js / .ts files are listed and resolvable but never returned by loadMany() under the default format set) is a pre-existing defect independent of loadManyKeyed(); its repair (option C: one shared name-to-path function for list(), findFile() and loadManyKeyed()) moves listNames() output and needs its own card — filed by this seat as a finding for triage (linked below once created). ⛔ Not in this PR.

PR shape: Fixes #14341 (the card's dispatchable half is the FilesystemLoader loadManyKeyed(); the RemoteLoader half is out of scope by triage, not deferred; the derivation defect has its own card). Pins: flat nameless body reaches MetadataManager.list(); flat named body keyed by basename (state the body.name-differs case); nested named file keeps its body.name key; nested nameless file still dropped (the honest drop, pinned as a record so C inverts it deliberately); extension-less named file keeps body.name. Ablation direction as dispatched. metadata: patch changeset. The test-layer program reading (NOT MEASURED — #14342) stays as reported.

---

Generated by Claude Code