Skip to content

Retire the paper metadata-customization protocol with its full coupling set — spec module, authorable customizationPolicies/mergeStrategy keys, metadata API §5, optional IMetadataService overlay methods, unreachable packages/metadata limb (re-charter of #12057) #13135

Description

@os-trump

Widened re-charter of #12057, executing the maintainer ruling of 2026-08-29 (comment 5459699497 on #12057: 「同意」 — retirement under ADR-0049 remove; re-scope explicitly not taken) as applied to the evidence of record (fork report, comment 5451357017 on #12057). The single-module deletion the original card described is not compilable — any compiling PR silently performs the wider removal — so this card charters that wider removal honestly.

Charter basis (all on #12057)

  • Maintainer ruling: comment 5459699497 (director batch [WIP] Create a new release version #9, 2026-08-29) — retirement adopted, re-scope rejected, execution through the normal dispatch lanes.
  • Decision analysis the ruling adopts: comment 5451376436 — recommendation A (widened retirement), with the pre-registered execution chain naming the spec seat.
  • Measurement base: fork report comment 5451357017, measured at objectstack 8beb3deaf / objectui efdc6c62. Re-verify every anchor on the current ref before cutting — first work item.
  • Model-level record: ADR-0126 §6.4 (docs/adr/0126-packaged-metadata-customization-model.md) — supersedes the module ("nothing may build against it") and charters retirement.

Retirement surface (from the fork report; re-verify each anchor)

  1. packages/spec/src/kernel/metadata-customization.zod.ts — module deletion; the kernel/index.ts:24 barrel line.
  2. kernel/metadata-plugin.zod.ts:6,499,505MetadataPluginConfigSchema.customizationPolicies and .mergeStrategy are authorable config keys embedding CustomizationPolicySchema/MergeStrategyConfigSchema → retire via the spec-property-retirement playbook routes in full (RETIRED_KEYS_BY_MAJOR, conversion registry, ledgers — the authorable-key discipline, not a bare delete).
  3. api/metadata.zod.ts:9,201,208 — section-5 Overlay/Customization API contracts built on MetadataOverlaySchema.
  4. contracts/metadata-service.ts:49,631-655 — optional getOverlay/saveOverlay/removeOverlay/getEffective members typed MetadataOverlay (contracts/ has no in-flight claim at filing time; IDataEngine.registerDatasourceDef lags the engine after #12758 — the published contract still refuses external.credentialsRef, and listDatasourceDefs is absent #12805 closed via merged PR feat(spec): IDataEngine datasource-def contract catches up to the engine — external.credentialsRef accepted, listDatasourceDefs declared #12949).
  5. kernel/metadata-loader.zod.ts:144persistence.overlayWritable (its describe names saveOverlay()).
  6. packages/metadata/src/metadata-manager.ts:45 import + the overlay limb (315-316 in-memory map; 2166-2245 getOverlay/saveOverlay/removeOverlay + getEffective patch application) — unreachable from any served surface (no route serves the paper endpoints; only its own unit tests call it). Remove the limb + its test cases (metadata-service.test.ts, metadata.test.ts overlay cases) + plugin.ts:347 'overlay' feature log entry + ROADMAP.md:176 row.
  7. src/type-alias-convention.pin.test.ts:164 (M86 rows Iso408-411) — adjust per that pin's own convention for removed modules.
  8. Regenerated artifacts: api-surface/kernel.json and whatever else the gates prove stale (api-surface/export-origins for contracts, json-schema manifest); the generated reference page content/docs/references/kernel/metadata-customization.mdx disappears with the module; ADR-0087 registration per the gate's own verdict; changeset.

Explicitly NOT in this card

  • ADR-0126 §6.4 "consumed by zero runtime packages" factual correction — separate draft-only PR card (governed surface, human merge).
  • objectui packages/types/src/views.ts:411 comment-only mention (already says "Do not re-point this at it") — cosmetic, no action.
  • Inline vocabulary twins that do NOT import the module (api/package-api.zod.ts:186 mergeStrategy enum; kernel/package-upgrade.zod.ts same three-value vocabulary) — separately declared surfaces, do not touch.

Stop conditions (report the fork on this card, never force)

  • Re-verification finds a consumer OUTSIDE the surface above (new coupling since 8beb3deaf), or ADR text contradicting retirement.
  • An authorable-key retirement route (conversion/ledger) demands a shape the playbook does not cover.

Serialization notes

Size: L. Clause-②: yes on both legs (PATH: packages/spec/src/**; CONTENT: public-export deletion narrows the published face) — fable-tier dispatch mandatory; needs:contract-review attaches when this card's PR exists.

Metadata

Metadata

Assignees

Type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions