Skip to content

Commit 6548121

Browse files
claudeclaude
committed
docs(spec): regenerate artifacts and record ADR-0141 D8's measured fates for the two dependency spellings
Claude-Session: https://claude.ai/code/session_01BkRZmjDUobsYmkGEjwjH9U Co-authored-by: Claude <noreply@anthropic.com>
1 parent 2e69d3e commit 6548121

8 files changed

Lines changed: 46 additions & 8 deletions

File tree

‎.changeset/25792-retire-dependency-spellings.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
'@objectstack/spec': minor
3+
---
4+
5+
**BREAKING** — the two unread dependency spellings leave the authoring surface: `PackageDependency.optional` (an entry of the marketplace snapshot's `manifestJson.dependencies[]`) and `AppManifest.dependencies` (the bare-id list on the app install manifest) are `retiredKey()` tombstones (#25792, ADR-0141 D8 items 2 and 3).
6+
7+
A `major`-class change, recorded as `minor` under the launch-window convention. ADR-0141 D8 left both fates to "a measured reader count"; the count was zero for both, so both retire at once, with no retirement stage (ADR-0049 enforce-or-remove).
8+
9+
Clause-②: no (narrowing)
10+
Metadata-protocol: narrowed
11+
12+
**Why.** A dependency is declared in one place, the package's `manifest.dependencies` record (`{ [packageId]: versionRange }`), and the ADR-0141 D2 pre-install check reads that record alone and treats every entry as required. Two more spellings stayed declared beside it and nothing read either. `optional: true` promised "missing dep is a warning, not an error", but the record has no optional arm, so no install path could honour it. `AppManifest.dependencies` restated the record without its range, and no install path consulted it. An author, often an AI, who wrote either got nothing enforced and no error. Measured at `origin/main` `6390fe52ce`: zero readers and zero writers of either key outside `packages/spec` (`packages/`, `ui/`, `examples/`, `apps/`), and none in HotCRM at `9464673`, whose three modules declare their dependency in the record.
13+
14+
### FROM → TO
15+
16+
| removed | from | what to write instead |
17+
| --- | --- | --- |
18+
| `optional` on a `PackageDependency` entry (`PackageManifestSchema.dependencies[]`) | `@objectstack/spec/marketplace` | delete the key. An entry carries `packageId` and `versionRange` only. Declare a dependency in `manifest.dependencies` only when the package cannot install without it. |
19+
| `dependencies` on `AppManifest` | `@objectstack/spec/system` | delete the key. Declare each dependency with its range in the package's `manifest.dependencies`, for example `{ 'com.acme.core': '^1.0.0' }`. |
20+
21+
**The one-line fix: delete the key.** A TypeScript author fails `tsc` first (each key is typed as the retired mark), and a parse of `PackageDependencySchema`, `PackageManifestSchema` or `AppManifestSchema` refuses the key with its prescription, the old default (`false`, `[]`) included. The parsed output no longer carries either key, so `PackageDependencyParsed` loses `optional` and `AppManifestParsed` loses `dependencies`.
22+
23+
⚠️ Runtime behaviour is deliberately **unchanged**: nothing ever read either key, so every install answers exactly as before. The removal retracts a false claim, not a capability. **No deprecation window** (startup-stage posture: retirements take effect immediately).
24+
25+
⚠️ **The out-of-repo consumer population beyond HotCRM is NOT MEASURED.** `@objectstack/spec` is published, and the control plane's reading of `sys_package_version.manifest_json` is not readable from this repository.
26+
27+
The ADR-0087 D3 semantic entry `dependency-unread-spellings-retired` carries the judgement, and both keys are registered in `RETIRED_KEYS_BY_MAJOR[18]`. There is no D2 conversion: neither shape is a stack collection member, so a conversion would have no source to rewrite.
28+
29+
<!-- adr-0087: registered dependency-unread-spellings-retired -->

‎content/docs/references/marketplace/package-version.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ Package dependency declaration
6464
| :--- | :--- | :--- | :--- |
6565
| **packageId** | `string` | ✅ | Manifest ID of the dependency |
6666
| **versionRange** | `string` | ✅ | Semver version range (e.g. ^1.0.0) |
67-
| **optional** | `boolean` | optional (default: `false`) | Whether this dependency is optional |
67+
| **optional** | `never` | optional | [REMOVED] `PackageDependency.optional` was removed in @objectstack/spec 18 (ADR-0049 enforce-or-remove, ADR-0141 D8) — no install path ever honoured it: the pre-install check reads the package's `manifest.dependencies` record, which has no optional arm, and treats every entry as required. Delete the key. Declare a dependency in `manifest.dependencies` (`{ 'com.acme.core': '^1.0.0' }`) only when the package cannot install without it. |
6868

6969

7070
---
@@ -83,7 +83,7 @@ Package manifest snapshot embedded in a package version
8383
| **description** | `string` | optional | Short description |
8484
| **scope** | `Enum<'platform' \| 'environment'>` | optional (default: `"environment"`) | Package scope |
8585
| **minPlatformVersion** | `string` | optional | Minimum required platform version (semver) |
86-
| **dependencies** | `{ packageId: string; versionRange: string; optional?: boolean }[]` | optional (default: `[]`) | Package dependencies |
86+
| **dependencies** | `{ packageId: string; versionRange: string }[]` | optional (default: `[]`) | Package dependencies |
8787
| **metadataTypes** | `string[]` | optional (default: `[]`) | Metadata types provided by this package |
8888
| **migrations** | `string[]` | optional (default: `[]`) | Migration script identifiers (ordered) |
8989
| **configurationSchema** | `Record<string, any>` | optional | JSON Schema for per-installation configuration properties |
@@ -97,7 +97,7 @@ Package dependency declaration
9797
| :--- | :--- | :--- | :--- |
9898
| **packageId** | `string` | ✅ | Manifest ID of the dependency |
9999
| **versionRange** | `string` | ✅ | Semver version range (e.g. ^1.0.0) |
100-
| **optional** | `boolean` | optional (default: `false`) | Whether this dependency is optional |
100+
| **optional** | `never` | optional | [REMOVED] `PackageDependency.optional` was removed in @objectstack/spec 18 (ADR-0049 enforce-or-remove, ADR-0141 D8) — no install path ever honoured it: the pre-install check reads the package's `manifest.dependencies` record, which has no optional arm, and treats every entry as required. Delete the key. Declare a dependency in `manifest.dependencies` (`{ 'com.acme.core': '^1.0.0' }`) only when the package cannot install without it. |
101101

102102

103103
---

‎content/docs/references/system/app-install.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ App manifest for marketplace installation
111111
| **flows** | `string[]` | optional (default: `[]`) | Flow names provided |
112112
| **hasSeedData** | `boolean` | optional (default: `false`) | Whether app includes seed data |
113113
| **seedData** | `Record<string, any>[]` | optional (default: `[]`) | Seed data records |
114-
| **dependencies** | `string[]` | optional (default: `[]`) | Required app dependencies |
114+
| **dependencies** | `never` | optional | [REMOVED] `AppManifest.dependencies` was removed in @objectstack/spec 18 (ADR-0049 enforce-or-remove, ADR-0141 D8) — nothing read it: it listed bare ids with no version range, and no install path consulted it. Delete the key. Declare each dependency with its range in the package's `manifest.dependencies` (`{ 'com.acme.core': '^1.0.0' }`), which the pre-install check enforces. |
115115

116116

117117
---

‎docs/adr/0141-inter-app-dependency-declared-checked-before-install.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -513,6 +513,17 @@ other two on the runtime card:
513513
The resolver-side `ResolvedPackageDependencySchema` (`@objectstack/spec/kernel`) is unaffected: it is a resolution outcome,
514514
not a declaration, and `PackageDependencySchema`'s own header already tells the two apart.
515515

516+
**Addendum (2026-10-27, #25792 item 6) — items 2 and 3 decided on the measured count: both retire.** Measured at
517+
`origin/main` `6390fe52ce`: `PackageDependencySchema.optional` has **0** readers and **0** writers outside `packages/spec`,
518+
and `AppManifestSchema.dependencies` has **0** readers and **0** writers there, with no parse of `AppManifestSchema` at all
519+
(this repository's `packages/`, `ui/`, `examples/` and `apps/`; HotCRM at `9464673`, whose three module manifests declare
520+
the record, the live control). Inside `packages/spec` the only authors were the two schemas and three of their own tests.
521+
Each key is a `retiredKey()` tombstone now (`marketplace/PackageDependency:optional` and `system/AppManifest:dependencies`
522+
in `RETIRED_KEYS_BY_MAJOR[18]`), with the D3 record `dependency-unread-spellings-retired` and no D2 conversion, because
523+
neither shape is a stack collection member. The projection above therefore carries `packageId` = the key and
524+
`versionRange` = the value, nothing else: item 1's conversion writes no `optional`, and `manifest.dependencies` is the
525+
one way to declare a dependency.
526+
516527
---
517528

518529
## Consequences

‎packages/spec/authorable-defaults/marketplace.json‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,6 @@
1313
"marketplace/Package:isStarter = false",
1414
"marketplace/Package:publisher = \"private\"",
1515
"marketplace/Package:visibility = \"org\"",
16-
"marketplace/PackageDependency:optional = false",
1716
"marketplace/PackageManifest:dependencies = []",
1817
"marketplace/PackageManifest:metadataTypes = []",
1918
"marketplace/PackageManifest:migrations = []",

‎packages/spec/authorable-defaults/system.json‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,6 @@
99
"system/AppInstallResult:createdTables = []",
1010
"system/AppInstallResult:installedObjects = []",
1111
"system/AppInstallResult:seededRecords = 0",
12-
"system/AppManifest:dependencies = []",
1312
"system/AppManifest:flows = []",
1413
"system/AppManifest:hasSeedData = false",
1514
"system/AppManifest:objects = []",

‎packages/spec/authorable-surface/marketplace.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@
102102
"marketplace/Package:translations",
103103
"marketplace/Package:updatedAt",
104104
"marketplace/Package:visibility",
105-
"marketplace/PackageDependency:optional",
105+
"marketplace/PackageDependency:optional [RETIRED]",
106106
"marketplace/PackageDependency:packageId",
107107
"marketplace/PackageDependency:versionRange",
108108
"marketplace/PackageManifest:configurationSchema",

‎packages/spec/authorable-surface/system.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@
4343
"system/AppInstallResult:seededRecords",
4444
"system/AppInstallResult:success",
4545
"system/AppInstallResult:version",
46-
"system/AppManifest:dependencies",
46+
"system/AppManifest:dependencies [RETIRED]",
4747
"system/AppManifest:description",
4848
"system/AppManifest:flows",
4949
"system/AppManifest:hasSeedData",

0 commit comments

Comments
 (0)