Skip to content

Commit 406ef40

Browse files
committed
Merge remote-tracking branch 'origin/main' into claude/harden-connector-undeclared-keys
Claude-Session: https://claude.ai/code/session_017xRBcVy4VXmkQjn2MGeaWk Co-authored-by: Claude <noreply@anthropic.com>
2 parents 14e25f5 + 6b9c1ca commit 406ef40

87 files changed

Lines changed: 4816 additions & 453 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
'@objectstack/metadata-protocol': minor
3+
'@objectstack/cli': minor
4+
'@objectstack/cloud-connection': minor
5+
'@objectstack/spec': patch
6+
---
7+
8+
**BREAKING** feat(metadata-protocol)!: the override write gate — only a base's paired `<base>.custom` package declares an override, and a dependent's item under a base item's name is refused (ADR-0146 D2, #28410)
9+
10+
Clause-②: yes (narrowing)
11+
Metadata-protocol: narrowed
12+
Skills-docs: none — no file under `skills/**` teaches the `overrides` declaration, a `<base>.custom` package or the sealed-write sentence; the `content/docs/references/**` pages that show `overrides` are generated from the spec and do not move.
13+
14+
<!-- adr-0087: not-required (no-migration-prescription) The narrowing is a refusal at the write doors (publish, `os validate`, the marketplace managed install) of item NAMES and of an `overrides` declaration outside the base's paired package: no metadata key, accepted value, export or error code is removed or renamed, and no stored shape changes. The remedy is a rename of an item, or a declaration added in the base's paired `.custom` package, both authoring choices a person makes; there is no mechanical conversion between two metadata versions for `objectstack migrate meta` to apply, and the precondition count on #28410 found no same-named item inside a dependency closure in hotcrm or the repository's examples. The other categories are closed on facts: all three packages publish (not unpublished); no ADR-0087 id is named or touched (not registered or already-registered); the one `packages/spec/**` file touched is the error-code provenance ledger (`api/error-code-ledger.zod.ts`), two rows naming new emitters of the already-registered `NOT_OVERRIDABLE`, so no schema, type or runtime interface moves (not type-surface-only, not runtime-interface-only); and no export is retired (not runtime-export-retired). -->
15+
16+
A dependent package used to be able to ship, publish or install an item under the name an item of a package in its dependency closure already has, and nothing said which one a reader would get. Ruling A on #28390 settles it: only the base's paired `<base>.custom` package declares an override (`overrides: { package: '<base>', basedOn }`), and a dependent's same-named item has one fix, rename.
17+
18+
**What is refused**, `403 NOT_OVERRIDABLE` (the code and status the sealed write already answers), each with its own sentence:
19+
20+
- **An undeclared same name inside the closure.** A dependent's item bearing the name of an item a read-only (installed) package in its dependency closure ships, on a type a declared override can replace. In `<base>.custom` the sentence says to declare it or rename it; in any other dependent, to rename it.
21+
- **`overrides` outside the pair.** A declaration on a package that is not the base's paired `.custom`.
22+
- **A declaration the closure cannot back.** `overrides.package` outside the declaring package's dependency closure (the sentence says to declare the dependency), or a base that ships no item of that type and name.
23+
- **A type that takes no override.** An excluded type (permission, position, capability, the code-only types…), pointing to creating a new item under a new name; an `object`, pointing to `objectExtensions`.
24+
- **A channel not yet open.** A declared `flow` ("flow customization is not yet available") or `action`.
25+
26+
**Where.** The save door (`saveMetaItem`, so `PUT /api/v1/meta/:type/:name` and every authoring path through it), the promotion (`publishMetaItem` and `publishPackageDrafts`), `os validate` (each package of the artifact against its closure inside the artifact; exit 1), and the marketplace managed install (`POST /api/v1/marketplace/install-local`, before any write). The undeclared-same-name refusal is asked last at the publish doors, so every refusal those doors already answered keeps its code and status.
27+
28+
**Admitted.** The base's paired `.custom` declaring an override of an item its base ships, on an open type: the save and the promotion write it as the pair's own row, and the managed install registers it.
29+
30+
**The install answer lists upgrade collisions.** An install of a base whose new version ships a name an installed dependent already holds, undeclared, answers `200` with `overrideCollisions` (`type`, `name`, `packageId`, `rule`, `message`), one row per held item; the key is omitted when there is none. The install is not refused: the dependent's item is the one to rename, or in `.custom`, to declare.
31+
32+
**The sealed sentence.** A write over a sealed item of a type a declared override can replace now names the writer's route in place of none. Written from the base's paired `.custom`, or naming no package, it ends "To change it, declare an override from '<base>.custom' (overrides: { package: '<base>', basedOn }), or rename the item."; written from any other package, "To change it, rename the item: only '<base>.custom' may declare an override of '<base>'."
33+
34+
**A malformed `overrides` is not a declaration.** A value the spec's `OverrideDeclarationSchema` refuses (null, not an object, no or an empty `package`, no `basedOn`) is not judged by the gate; the save door's schema gate answers it (`422 INVALID_METADATA`), and `os validate` reports it at its schema step.
35+
36+
`@objectstack/metadata-protocol` exports the gate's rule, `judgeOverrideWrite`, and its item walk, `overrideWriteItemsOf`, so the three doors ask one judgement.
37+
38+
`@objectstack/spec` records the two new emitters of `NOT_OVERRIDABLE` in its error-code provenance ledger (`api/error-code-ledger.zod.ts`, under `@objectstack/cli` and `@objectstack/cloud-connection`). The code was already registered, so the union, casing and every schema are unchanged.
Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
"@objectstack/cloud-connection": minor
3+
---
4+
5+
fix(cloud-connection)!: every member of an installed bundle is recorded as installed, whatever its entry's `source` states
6+
7+
`POST /api/v1/marketplace/install-local` (and `os package install`) now registers every member of a `packages[]` bundle as `source: 'marketplace'`, at the install and at every restart's rehydrate. The `manifest` service stamps an entry's own `source` over the door's, so a member whose entry said `'code'` was recorded as the host's own code, and readers of a package's origin treated it so: the connector materializer let its package-relative file refs read the host's directory.
8+
9+
Clause-②: no (narrowing) — at the install-local door a `packages[]` entry's stated `source` no longer decides the member's recorded origin: a member stating `'code'` is recorded `'marketplace'`, as the door states. Nothing is widened.
10+
11+
Metadata-protocol: narrowed (an installed bundle member's `source: 'code'` is no longer honoured at the install door)
12+
13+
<!-- adr-0087: not-required (no-migration-prescription) No key is added, removed or renamed and no body is refused: the entry's `source` is still accepted, and still honoured where it means something, the boot of a merged artifact; at the install door the door's own statement wins, and it is the origin of every package this door registers. There is nothing for an author or a migration to rewrite. -->
14+
15+
**BREAKING** semantic narrowing at the install-local door (`@objectstack/cloud-connection`), shipped as `minor`.
16+
17+
- **Before.** A bundle installed through the door whose second member's entry stated `source: 'code'` recorded that member as `'code'`, and a ledger entry holding such a bundle did so again at every restart.
18+
- **Now.** Both members are recorded `'marketplace'`, at the install and at the rehydrate, so a ledger entry written earlier is recorded the same way after the next restart.
19+
- **Unchanged.** The `manifest` service's precedence for a boot that registers a merged artifact stating no source of its own: each entry's statement still stands there. An entry stating `'marketplace'` or nothing is handed through as received.
20+
- **Who sees it.** A bundle installed through this door whose entry claimed `'code'`. Its members now read as installed everywhere a package's origin is read.
21+
22+
**The remedy.** None is owed. Drop the entry's `source` if it was written for this door: the door states the origin of what it installs.
Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
"@objectstack/service-automation": patch
3+
---
4+
5+
fix(service-automation)!: an installed package's connector entry never reads the host's files
6+
7+
A connector entry declared by a package that was installed into the runtime (`os package install`, `POST /api/v1/marketplace/install-local`; the package registry's `source: 'marketplace'`) was handed `loadPackageFile` / `resolvePackagePath` anchored at the HOST's root, whichever package declared it. An installed package has no directory on the runtime it is installed into, so a relative ref resolved against another package's files: an installed `openapi` connector naming `./src/system/connectors/status-openapi.json` materialized `ready` with the showcase's own document, and a stdio `mcp` connector naming `./scripts/mcp-fixture.mjs` spawned the showcase's own fixture in the showcase's directory.
8+
9+
Clause-②: no (narrowing) — a connector entry that is not the host's own (an installed package's, or one whose stamp no registration records) is refused its package-relative file and path refs, which it was handed before against the host's root. Nothing is widened.
10+
11+
Metadata-protocol: narrowed (an installed package's connector `providerConfig` may no longer name a package-relative file, and an installed package's stdio `mcp` transport is refused)
12+
13+
<!-- adr-0087: not-required (no-migration-prescription) No key is added, removed or renamed and the stored shape is unchanged: the same `providerConfig` is accepted, and what is refused is the host's root being read on the installed package's behalf. No conversion can carry a file the install never held; the refusal names the entry, its package, the ref and the remedy, and a current `os build` already writes the document into the artifact. -->
14+
15+
**BREAKING** behaviour narrowing for installed packages' connectors (`@objectstack/service-automation`), shipped as `patch` beside the `minor` of `@objectstack/objectql` and `@objectstack/cloud-connection` that carries the same declaration.
16+
17+
- **Before.** An installed package's entry naming a package-relative file or location read the host's own file, or ran a stdio process in the host's directory.
18+
- **Now.** Both members refuse every ref for such an entry, naming the entry, its package and the ref: a configuration fault, so the instance is not materialized and the reconcile logs the refusal. Whose entry it is comes only from what a registering door recorded (the package row's `source`, or the residual owner's door for an artifact residual), never from the entry's own words: an entry stamped with a package no registration records is refused its refs as well.
19+
- **Unchanged.** An entry carrying its document inline or as an `http(s)` URL, and every entry of the host's own stack, which keeps reading its files as before.
20+
- **Who sees it.** An installed package whose connector names a package-relative `openapi` spec, or declares a stdio `mcp` transport.
21+
22+
**The remedy.** Rebuild the package with a current `os build`, which carries an `openapi` spec file into the artifact, or inline the document; an installed package reaches an MCP server over `http`, since a stdio transport needs a working directory inside the package.
Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
"@objectstack/objectql": minor
3+
---
4+
5+
fix(objectql)!: a collection item never names its own owning package — package registration refuses a body `_packageId` other than the registering package's
6+
7+
`ObjectQL.registerApp` (a manifest and its nested plugins, seed datasets included) and the `manifest` service's ADR-0130 residual registration now refuse a collection item whose body already carries a `_packageId` other than the package registering it: `VALIDATION_ERROR` / 400 with `issues[]` at `_packageId`, before the item is filed, the envelope of the permission-set owner refusal in the same loop. The registration stamps `_packageId` only while it is unset, so a body could wear another package's id (an installed connector naming the host's own package, or an id nobody holds) and every reader of an item's owner, the connector materializer deciding whose directory a file ref resolves against among them, read the body's claim about itself.
8+
9+
Clause-②: no (narrowing) — package registration refuses a collection item whose body `_packageId` names a package other than the one registering it, which it registered before with the body's stamp kept. Nothing is widened.
10+
11+
Metadata-protocol: narrowed (a collection item's `_packageId`, declared by `MetadataProtectionFields`, may no longer name a package other than the one that registers it)
12+
13+
<!-- adr-0087: not-required (no-migration-prescription) No key is added, removed or renamed, and no value a legitimate producer writes is refused: the registration is the only writer of `_packageId` (`os build` writes none, the package export strips every underscore key, the artifact loader stamps with the very id the registration keys on), so a foreign stamp exists only in a body somebody wrote by hand to claim another owner. A D2 conversion could not tell such a stamp from an agreeing one without the registration that judges it, and the refusal names the item, both ids and the remedy. -->
14+
15+
**BREAKING** accept-set narrowing at package registration (`@objectstack/objectql`), shipped as `minor`.
16+
17+
- **Before.** A manifest `com.acme.app` whose connector carried `_packageId: 'com.acme.host'` registered the connector with that stamp kept, with no refusal and no warning; so did a nested plugin's item, a seed dataset and a multi-package artifact's residual item. `null` and `''` were kept too.
18+
- **Now.** The registration throws `400 VALIDATION_ERROR` with `issues[]` at `_packageId`, naming the item, the stamp and the package registering it, before anything of the item is filed. Through `POST /api/v1/marketplace/install-local` an inline install answers `422 PLUGIN_REGISTER_FAILED` with that message and persists nothing.
19+
- **Unchanged.** An absent `_packageId` and one equal to the registering package register as before. An item object that an earlier registration stamped in place (a module constant handed to a second registration) registers as it always has: only a stamp the object arrives with is judged. Objects (`objects`) are not judged by this seam.
20+
- **Who sees it.** Whoever hand-writes `_packageId` on a manifest item naming another package, which no build, export or install writes.
21+
22+
**The remedy.** Remove `_packageId` from the item. The package an item belongs to is the one that registers it, stamped by the registration.
23+
24+
The `manifest` service also records which door registered each multi-package artifact's residual owner (`ObjectQL.recordResidualOwner` / `residualOwnerSource`: `'code'` for the boot, `'marketplace'` for an install), the only record of that id's origin, since the residual has no package row.
Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
'@objectstack/runtime': patch
3+
---
4+
5+
feat(runtime)!: the permission-set clone door lands "new similar" in a writable target package — by default the source package's `.custom`, never package-less (#28563)
6+
7+
Clause-②: yes (narrowing) — `POST /security/permission-sets/:name/clone` takes an optional `package` and its answer names the package the copy landed in (widening); a copy of a set shipped by a read-only package now lands in that package's paired `<X>.custom`, ensured through the pair's one creation path, so a source whose package the ensure door refuses (it declares no namespace, its version is not SemVer, or another package owns the pair's namespace) is refused 409/422 where it was copied package-less before, and a given target that is unknown, read-only or out of reach is refused.
8+
Metadata-protocol: none
9+
10+
<!-- adr-0087: not-required (no-migration-prescription) No metadata key, value or type changes: the door's HTTP body gains an optional key and its answer gains one, and the copy's own definition is the same whole-definition copy as before. A refused clone writes nothing and its refusal names the remedy, so there is nothing stored for a migration to rewrite and no tombstone. -->
11+
12+
**BREAKING** accept-set narrowing at the permission-set clone door (`@objectstack/runtime`).
13+
14+
- **Before.** Every copy was saved environment-wide with no package, whatever package shipped the set it was copied from. The body was `{ name, label }`.
15+
- **Now (ADR-0146 D3/D6).** The body is `{ name, label, package? }` and the answer is `{ permissionSet, package, notice }`.
16+
- `package` omitted, the set shipped by a read-only package X: the copy is saved in X's paired customization package `<X>.custom`, created through the ensure door (`ensureCustomizationPackage`) on the first copy and reused after. The stored row is bound to the pair; the copy's definition still names no package.
17+
- `package` omitted, the set already in a writable package (a base you own, or `<X>.custom`): the copy is saved in that package.
18+
- `package` omitted, the set authored in the environment: unchanged, environment-wide (`package: null`).
19+
- `package` given: it must be installed and writable (else 422 `WRITABLE_PACKAGE_REQUIRED`), and its dependency closure must reach the source's package and every object the set grants on (else 409 `RESOURCE_CONFLICT`). The rule is the one the flow clone door uses.
20+
- **Unchanged.** A new name is mandatory and a taken one is 409; `manage_metadata` and the walled catalog refusal answer first; the copy is assignable by its bare name through a position or a direct assignment.
21+
- **Who sees it.** An administrator copying a packaged set from Setup: the copy now travels with the package's customizations. A copy of a set from a package the ensure door cannot pair is refused with the ensure door's own sentence.
22+
23+
**The remedy.** For a refused pair: give the base package a namespace (and a SemVer version), or name a writable target with `package`.
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
'@objectstack/service-automation': patch
3+
---
4+
5+
fix(service-automation): a connector an installed package declares is live again after the runtime restarts
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
After a restart, the install-local rehydrate registers every installed package again, but in its `kernel:ready` handler. That is after the automation service's boot reconcile in `start()`, and the rehydrate announces no reload. The package was listed by `GET /api/v1/marketplace/install-local` and its flows bound, but its provider-bound connector instances were absent from `GET /api/v1/automation/connectors` until some unrelated metadata reload. Every flow step that called them failed at dispatch.
11+
12+
The automation service now reads the connector declaration once more at `kernel:bootstrapped`, which fires after every `kernel:ready` handler has settled, whatever the plugin order. It reconciles only when that declaration differs from the one the boot reconcile read. A boot that registers no connector after `start()` runs no second reconcile. This reconcile uses reload semantics: a configuration fault in a connector registered during `kernel:ready` (an unknown provider, an invalid `providerConfig`) is logged at `error` and that entry is skipped. It does not fail the boot. This is the same treatment the entry gets when it is installed into a running server.

0 commit comments

Comments
 (0)