Skip to content

Commit fda28c8

Browse files
committed
wip(spec): ADR-0087 D3 entry, ledger re-class, docblock refresh
Claude-Session: https://claude.ai/code/session_017xRBcVy4VXmkQjn2MGeaWk Co-authored-by: Claude <noreply@anthropic.com>
1 parent b9e26de commit fda28c8

5 files changed

Lines changed: 46 additions & 11 deletions

File tree

‎docs/audits/2026-07-unknown-key-strictness-ledger.counts/integration.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,4 +19,4 @@ hand-patch a number here** — fix the code or the verdict and regenerate.
1919

2020
| Dir | Sites |
2121
|---|---|
22-
| `integration/` | 3 |
22+
| `integration/` | 4 |

‎docs/audits/2026-07-unknown-key-strictness-ledger.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1375,7 +1375,7 @@ rest at #5107.
13751375
| `kernel/` | **mixed · `manifest.zod.ts` authorable, the rest wire** | ⚠️ **Split at #14192 — the flat `wire` verdict this row carried was right for the directory and wrong for one file in it, the `api/` row's finding one directory over.** `kernel/manifest.zod.ts` is `manifest:` — the hand-authored identity block of every `objectstack.config.ts`, every `os init` template, every example app, the Studio package form and the `objectstack.plugin.json` that `os plugin build` reads — and it was a plain open `z.object` under a cell that read "code-to-code". Measured first (2026-09-02 at `bd4aa4e49`, from `src` and through the built `dist`, identical readings): an unknown key parsed green and was DROPPED at all seven doors that reach `ManifestSchema` — the stack `manifest:` member (`defineStack` / `os validate` / `os compile`), `devPlugins[]`, the artifact `packages[]` entry in both its authoring and assembled forms, `os plugin build`, the `InstalledPackage` row schema, and the six package request/snapshot wire shapes that embed it. A transposed `namesapce` left `manifest.namespace` undefined at every one of them with exit 0 — and that key decides table names, REST paths and the install-time namespace gate (ADR-0129 D1–D2, ADR-0048 §3.2, ADR-0130 D1/D3). The same silent drop held one level down for `contributes` (`kind:` for `kinds:`), `contributes.kinds[]` and `engines` (`protocl:` for `protocol:`, which switches the load-time protocol handshake off). **The order the `api/` row records was kept: measurement, then the close.** No stored-row caller feeds this schema — `registry.validate('package' \| 'plugin')` has no live caller (`installPackage` stores the caller's object verbatim, `registerPlugin` is uncalled), the durable `sys_packages` row is re-registered through `registerApp` without a parse, and no bookkeeping key (`packageId` / `state` / `published*` / `package`) reaches any door — so the `peelStoredEnvelope` debt the `api/` row had to pay first does not exist here, and no bookkeeping key was taught to the authoring schema. Exactly ONE undeclared key was found at a real door, and it was DECLARED rather than curated: `main`, which `os plugin build` reads off the source `objectstack.plugin.json` to pick its entry and writes back into the compiled manifest as `dist/index.mjs`; three CLI fixtures author it, and a naked `strictObject` would have refused every plugin that names its entry — the shape this row would otherwise have recorded as refused. `ManifestSchema`, `contributes`, `contributes.kinds[]`, `engine` and `PluginEnginesSchema` are `strictObject` now: an undeclared key is a named rejection carrying the surface, the key and a rename (`namesapce` → `namespace`, `protocl` → `protocol`); the retired keys keep their `retiredKey()` tombstones (a tombstone types the key `never` and carries the upgrade text, which a bare refusal would not, and `acceptsNothing` keeps them out of the rename candidates); one curated wrong-layer pointer ships, `specVersion` (the retired CLI advisory axis — the live one is `engines.protocol`). `AssembledPackageBodySchema` (`stack.zod.ts`) inherits the closed posture through `.extend()`, so the load gate refuses an undeclared key on an assembled body too; that file's docblock sentence "NOT `strictObject`: `ManifestSchema` is an open object" is stale as of this change and is reported for its owner rather than edited here. Blast radius, measured with a strict preview before the close: 0 undeclared keys across the four example apps, the three `os init` templates, the `create-objectstack` blank template, the downstream-contract stack, the empty-kernel host and the i18n service manifest; the only shipped-block failure — `packages/cli/src/commands/create.ts`'s template manifest — fails the OPEN schema too (it lacks `id` and `type`) and is reported separately. Cloud is NOT MEASURED for this file (no checkout in the container, code search refused); if cloud parses a published `.osplugin` manifest through this schema, the compiled manifest it receives carries only declared keys (`main` and `integrity` included) by construction of `os plugin build`. The rest of `kernel/` is unchanged: plugin/kernel contracts, code-to-code |
13761376
| `cloud/` | wire | multi-tenant runtime |
13771377
| `ai/` | mixed | agent/tool/skill definitions authored (partially strict already); model/provider payloads wire |
1378-
| `integration/` | wire | connector payloads — upstream adds fields freely |
1378+
| `integration/` | **mixed · `connector.zod.ts`'s declarative entry authorable, the rest wire** | ⚠️ **Split at the connector-entry close — the flat `wire` verdict this row carried was right for the payloads and wrong for one shape, the `api/` and `kernel/` rows' finding again.** `DeclarativeConnectorEntrySchema` is the `connectors:` stack collection and the `connector` row the metadata save door keeps (`PUT /api/v1/meta/connector/:name`, bound in `UNREGISTERED_KIND_SCHEMAS`, which stores the request body for every type but `view` — ADR-0005 appendix (c), ruling B): an AUTHORED, STORED, SERVED type, not an upstream payload, yet it was a plain `z.object`, so an undeclared top-level key parsed green at every door that reads it. It is closed through a dedicated `strictObject` carrier (`DeclarativeConnectorEntryBaseSchema`) built from the same shape factory as the open one, each with its own field instances so `computeGuidanceRoutes()` never pairs the open `Connector` def with the closed declaration's `guidance`. Every door that parses the entry — `defineStack({ connectors })`, `os validate` / `os compile`, the artifact load at boot and reload, and the save door (`422 INVALID_METADATA`) — refuses the key by name, located at it; two curated families ride the refusal: credential-shaped keys → `auth.credentialRef`, provider settings → `providerConfig`. The ADR-0010 envelope was already declared on the shape (commit b5404f496), so no stamped entry is refused. Governing texts read before the close: ADR-0097, ADR-0143, ADR-0104 and the type-schema suite's #2657 fence — none keeps the authored entry open; the `ConnectorSchema is NOT .strict()` sentences across `connector.zod.ts` state the fact that made each retirement a `retiredKey()` tombstone, not a decision to stay open. ⛔ Deliberately NOT closed: `ConnectorSchema`, the def a plugin hands to `registerConnector` (code-to-code — the wire half of this row) and the shape `defineConnector()` parses, so `defineConnector({ … })` still drops an undeclared key before the entry sees it; closing that carrier is its own decision. The rest of `integration/` is unchanged: connector payloads, upstream adds fields freely |
13791379
| `identity/` | mixed | position/user shapes authored (`PositionSchema` **strict as of #4001 step 2**, with the ADR-0010 envelope declared); auth payloads wire. **34 → 33 in #4641**: `identity.zod.ts` lost its `SessionSchema` site — a second, importerless declaration of a name `api/auth.zod.ts` already owned (the #4411 dual-source trap), deleted rather than reclassified |
13801380
| `shared/` | **mixed · `protection.zod.ts` and `http.zod.ts`'s rate-limit budget authorable, the rest as written** | ⚠️ **Annotated again at #18578 — a FOURTH instance of the same shape, and this one was invisible to a sweep that went looking for it.** `shared/http.zod.ts`'s `RateLimitConfigSchema` is a building block with two mounts, and this row's rationale — *strictness decided at the consuming schema* — held for exactly one of them: `system/stack-server.zod.ts` re-postured it closed, and it did so by building `strictObject(…, RateLimitConfigSchema.shape)` **from this shape object**, so ONE declaration answered for TWO emitted defs with OPPOSITE doors. `api/endpoint.zod.ts` mounts the same schema BARE on `apis[].rateLimit` — a registered metadata type since #5312, authored through `defineStack({ apis })`, the Studio form and `PUT /meta/api/:name` — where nothing re-postures it, so the two `guidance` entries (`keyBy`, `store`) prescribed to nobody and a misspelled budget was worse: `windowSeconds: 60` parsed green and metered the 60000 ms default, a thousandfold miss reported as success. ⚠️ **The sweep that should have caught it could not.** A `CONTRACT_REVIEW_TIER` review swept this exact class with live controls (5 `.strip()` sites, 0 `z.object(XSchema.shape…)`, 0 `z.object(bareIdentifier)`) and found nothing, because the sharing runs the other way round here: it hunted an OPEN clone built from a STRICT schema's shape, and this is the STRICT one built from the OPEN one's shape — every grep shape in that sweep is blind to that direction by construction. It was found instead by driving the gate's own instrument (`computeGuidanceRoutes()` in `scripts/build-schemas.ts`) over every emitted def: match each def to its declaration, then ask the def what it actually does with the key. Census on `42f8df1723`: 1527 emitted defs, 258 resolving to exactly one declaration, 779 keys promised, **770 delivered, 9 not** — 2 of them this live silent strip, the other 7 union defs whose discriminator the probe's one-key document cannot supply (they DO deliver to an author who writes a whole document). The close moves the strictness and both tables onto the shared schema, leaving ONE declaration and ONE door for both defs: 772 delivered, 7 not. ⚠️ The residual 7 are a PROBE boundary, ⛔ not a clean zero and ⛔ not a finding. ⚠️ **Annotated at #16845 — the flat `n/a` verdict this row carried was right for the directory and wrong for one file in it, the `api/` and `kernel/` rows' finding a third time.** — the flat `n/a` verdict this row carried was right for the directory and wrong for one file in it, the `api/` and `kernel/` rows' finding a third time.** ⛔ **This directory is still UNTRIAGED and this is not a per-file row** — `shared/` has never had per-file rows, so `shared/protection.zod.ts` was **never enumerated** by this campaign; it was not deliberately accepted, because no verdict was ever taken on it. Two measurements say why the silence carried no information. **①** This row's own rationale — *strictness decided at the consuming schema* — is false for this file: all **16** `protection: ProtectionSchema` mounts across **14** files are the bare `ProtectionSchema.optional()`, not one `.extend()` / `.merge()` / `.omit()` / re-posture among them, so both the strictness and the MESSAGE are decided here in `shared/` and inherited verbatim by objects, views, dashboards, datasets, reports, apps, flows, webhooks, permissions, positions, email templates, agents, tools and skills — very nearly every authorable metadata type in the platform. A row is read as licence, which is what this ledger's own gate exists to prevent. **②** Even a per-file row would not have surfaced the defect, and this is the part worth keeping: `ProtectionSchema` has been `.strict()` since it was introduced, so it counts in the `strict` column and could never carry a remaining-strip row. **This ratchet's axis is CLOSURE; the defect was MESSAGE QUALITY** — a closed shape with no error map, refusing `lockk` with zod's bare `Unrecognized key: "lockk"`: no surface, no declared-key list, no rename, on every one of those mounts. `strictObject` at #16845 (the `PluginPermissionsSchema` conversion at #16328 one directory over is the precedent). ⛔ The population of *closed shapes still carrying zod's bare message* is **NOT MEASURED** here and is not this row's claim — #14722's rule stands that a sweep needs its own card with its own measured count. The rest of `shared/` is unchanged: utilities and building blocks whose strictness really is decided at the consuming schema |
13811381
| `qa/` | n/a | test fixtures |

‎packages/spec/src/integration/connector.zod.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -421,8 +421,8 @@ const ERROR_MAPPING_RETIRED =
421421
// ============================================================================
422422
//
423423
// A bounded (`min(1000).max(300000)`), defaulted (`30000`), `.describe()`d key
424-
// on this schema and — because both published carriers wrap the same private
425-
// `ConnectorBaseSchema` — on
424+
// on this schema and — because both published carriers are built from the same
425+
// private connector shape (`connectorBaseShape`) — on
426426
// `DeclarativeConnectorEntrySchema`, so it was authorable from `stack.connectors[]`,
427427
// from `PUT /meta/connector/:name`, and served back by `/meta/connector`. Every
428428
// signal an authoring surface can give said it worked.
@@ -582,7 +582,7 @@ const CONNECTOR_RETIRED_KEY_RESIDUE = {
582582
// `ConnectorSchema` is NOT `.strict()`, so a plain delete would be a silent
583583
// strip (ADR-0104): each carrier key is a `retiredKey()` tombstone below,
584584
// inherited by `DeclarativeConnectorEntrySchema` because both published
585-
// carriers wrap the same private `ConnectorBaseSchema`. The shapes behind them
585+
// carriers are built from the same private `connectorBaseShape`. The shapes behind them
586586
// leave whole — `integration/ConnectorHealth`, `integration/HealthCheckConfig`,
587587
// `integration/CircuitBreakerConfig`, `integration/ConnectorStatus`,
588588
// `integration/WebhookConfig`, `integration/WebhookEvent` and
@@ -1035,7 +1035,7 @@ const connectorBaseShape = () => ({
10351035
* would be a silent strip (ADR-0104); the tombstone makes the removal audible
10361036
* in the two channels an upgrading author actually hits — `tsc` and the
10371037
* parse — and `DeclarativeConnectorEntrySchema` carries it too (both
1038-
* published carriers wrap the same private `ConnectorBaseSchema`; until the
1038+
* published carriers are built from the same private `connectorBaseShape`; until the
10391039
* `connectionTimeoutMs` retirement the entry schema was literally
10401040
* `ConnectorSchema.superRefine(...)`), so `stack.connectors[]` and the
10411041
* `/meta/connector` door refuse

‎packages/spec/src/kernel/metadata-type-schemas.test.ts‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -318,9 +318,12 @@ const UNDECLARED_ENVELOPE_UNREGISTERED = new Set<string>([]);
318318
* alone: the #4001 closure campaign and its count (the `describe` below),
319319
* `metadata-create-seeds`, `MetadataTypeSchema` membership,
320320
* `DEFAULT_METADATA_TYPE_REGISTRY` descriptors. In particular there is
321-
* deliberately NO unknown-key/posture case here — `sharing_rule` is strict and
322-
* `connector` is not, and choosing between them is #2657's decision to make, not
323-
* this suite's.
321+
* deliberately NO unknown-key/posture case here — `sharing_rule` was strict and
322+
* `connector` was not when this fence was drawn, and choosing between them was
323+
* #2657's decision to make, not this suite's. (The connector entry has since
324+
* closed on its own evidence — its pins live in
325+
* `integration/connector-entry-undeclared-keys.test.ts` — and the fence still
326+
* holds: this block asserts the envelope and nothing else.)
324327
*/
325328
describe('the envelope invariant also covers UNREGISTERED_KIND_SCHEMAS', () => {
326329
const bound = listUnregisteredKindSchemaTypes();
@@ -372,8 +375,9 @@ describe('the envelope invariant also covers UNREGISTERED_KIND_SCHEMAS', () => {
372375
it.each(bound.filter((t) => !UNDECLARED_ENVELOPE_UNREGISTERED.has(t)))(
373376
'%s DECLARES the protection envelope',
374377
(type) => {
375-
// `connector`'s class: non-strict + undeclared ⇒ a SILENT strip, no 422,
376-
// nothing in any log. The quieter half, and the one that survived #6245.
378+
// `connector`'s class when this was written: non-strict + undeclared ⇒ a
379+
// SILENT strip, no 422, nothing in any log. The quieter half, and the one
380+
// that survived #6245.
377381
const shapes = objectShapes(getMetadataTypeSchema(type));
378382
expect(
379383
shapes.some((shape) => '_packageId' in shape),
Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
import type { SemanticMigration } from '../../types.js';
4+
5+
export const entry: SemanticMigration = {
6+
id: 'connector-entry-undeclared-key-refused',
7+
surface: 'connector entries AUTHORED through defineStack `connectors:`, `os validate` / `os compile`, the ' +
8+
'artifact load and `PUT /meta/connector/:name` — a top-level key the entry does not declare',
9+
replacement: 'keep only the keys `DeclarativeConnectorEntrySchema` declares. A provider setting moves under ' +
10+
'`providerConfig` (`baseUrl` for `rest`, `spec` / `baseUrl` for `openapi`, `transport` for `mcp`); a ' +
11+
'credential goes into the secrets layer under the name `auth.credentialRef` gives (an environment variable ' +
12+
'in the open tier, or Setup → Connector credentials) and the key is deleted; free-form notes go in ' +
13+
'`description` or `metadata`.',
14+
reason:
15+
'The authored entry was a plain object, so an undeclared top-level key parsed green at every door and ' +
16+
'meant nothing to the runtime: no provider, the automation service or the dispatcher ever read one. It is ' +
17+
'refused now, by name and located at the key, with a prescription for the two families an author most ' +
18+
'often misplaces: a credential and a provider setting. There is deliberately no mechanical rewrite: an ' +
19+
'undeclared key may be a misplaced provider setting whose right home depends on the provider, or a secret ' +
20+
'whose only copy is the value written there, and where either goes next is a judgement about the ' +
21+
'connector, not a rename. The runtime connector shape (`ConnectorSchema`, the def a plugin hands to ' +
22+
'`registerConnector`) is unchanged. The metadata read also now withholds the credential parts of a URL ' +
23+
'under `providerConfig` (userinfo and credential query parameters) and an `auth` or `authentication` ' +
24+
'value that is not an object.',
25+
acceptanceCriteria:
26+
'Every authored connector entry parses through `DeclarativeConnectorEntrySchema` with no ' +
27+
'`unrecognized_keys` issue at its root; each misplaced provider setting sits under `providerConfig` and ' +
28+
'the instance still materializes (`GET /api/v1/automation/connectors` reports it `ready`); each secret ' +
29+
'that sat at a top-level key is set under its `credentialRef` name; no stored `sys_metadata` connector ' +
30+
'row reports an undeclared top-level key in its `_diagnostics`.',
31+
};

0 commit comments

Comments
 (0)