Skip to content

Commit 104d9e8

Browse files
committed
chore(spec): regenerate artefacts for the override declaration; type the new tests
Regenerated skill references, api-surface, export-origins, declaration-map, reference docs, the strictness-ledger counts and the authorable surface for the override declaration and the pairing helpers. The two new test files now pass the test typecheck without a debt entry. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017ihL2fi9zfJhUTubyJYb6V
1 parent 2b51218 commit 104d9e8

40 files changed

Lines changed: 318 additions & 10 deletions

File tree

‎content/docs/references/api/automation-api.mdx‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,7 @@ const result = AutomationApiErrorCode.parse(data);
129129
| **_packageId** | `string` | optional | Owning package machine id. |
130130
| **_packageVersion** | `string` | optional | Owning package version. |
131131
| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. |
132+
| **overrides** | `{ package: string; basedOn: string }` | optional | Override declaration (ADR-0146 D2): `{ package, basedOn }` — this item of "`<base>`.custom" replaces the base package's same-named item whole. `basedOn` is recorded and never judged. |
132133

133134
### Nested Shape: `CreateFlowRequest.variables[number]`
134135

@@ -186,6 +187,13 @@ const result = AutomationApiErrorCode.parse(data);
186187
| **reason** | `string` | ✅ | User-visible reason shown when the lock blocks an action. |
187188
| **docsUrl** | `string` | optional | Optional URL the Studio banner links to for more context. |
188189

190+
### Nested Shape: `CreateFlowRequest.overrides`
191+
192+
| Property | Type | Required | Description |
193+
| :--- | :--- | :--- | :--- |
194+
| **package** | `string` | ✅ | The base package id whose same-named item this item replaces whole (e.g. "com.acme.crm"). Only an item of the base's paired "`<base>`.custom" package declares an override. |
195+
| **basedOn** | `string` | ✅ | Recorded, never judged: the version of the base item this override was taken from (e.g. "3.2.0"). No door compares it with the installed base, no upgrade diff is produced from it, and nothing is refused on it; it tells a person re-basing the override where it started (ADR-0146 D2). |
196+
189197

190198
---
191199

@@ -249,6 +257,7 @@ const result = AutomationApiErrorCode.parse(data);
249257
| **_packageId** | `string` | optional | Owning package machine id. |
250258
| **_packageVersion** | `string` | optional | Owning package version. |
251259
| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. |
260+
| **overrides** | `{ package: string; basedOn: string }` | optional | Override declaration (ADR-0146 D2): `{ package, basedOn }` — this item of "`<base>`.custom" replaces the base package's same-named item whole. `basedOn` is recorded and never judged. |
252261

253262

254263
---
@@ -789,6 +798,7 @@ const result = AutomationApiErrorCode.parse(data);
789798
| **_packageId** | `string` | optional | Owning package machine id. |
790799
| **_packageVersion** | `string` | optional | Owning package version. |
791800
| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. |
801+
| **overrides** | `{ package: string; basedOn: string }` | optional | Override declaration (ADR-0146 D2): `{ package, basedOn }` — this item of "`<base>`.custom" replaces the base package's same-named item whole. `basedOn` is recorded and never judged. |
792802

793803

794804
---
@@ -1098,6 +1108,7 @@ const result = AutomationApiErrorCode.parse(data);
10981108
| **_packageId** | `string` | optional | Owning package machine id. |
10991109
| **_packageVersion** | `string` | optional | Owning package version. |
11001110
| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. |
1111+
| **overrides** | `{ package: string; basedOn: string }` | optional | Override declaration (ADR-0146 D2): `{ package, basedOn }` — this item of "`<base>`.custom" replaces the base package's same-named item whole. `basedOn` is recorded and never judged. |
11011112

11021113

11031114
---
@@ -1162,6 +1173,7 @@ const result = AutomationApiErrorCode.parse(data);
11621173
| **_packageId** | `string` | optional | Owning package machine id. |
11631174
| **_packageVersion** | `string` | optional | Owning package version. |
11641175
| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. |
1176+
| **overrides** | `{ package: string; basedOn: string }` | optional | Override declaration (ADR-0146 D2): `{ package, basedOn }` — this item of "`<base>`.custom" replaces the base package's same-named item whole. `basedOn` is recorded and never judged. |
11651177

11661178

11671179
---

‎content/docs/references/api/metadata.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,7 @@ const result = AppDefinitionResponseSchema.parse(data);
105105
| **_packageId** | `string` | optional | Owning package machine id. |
106106
| **_packageVersion** | `string` | optional | Owning package version. |
107107
| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. |
108+
| **overrides** | `{ package: string; basedOn: string }` | optional | Override declaration (ADR-0146 D2): `{ package, basedOn }` — this item of "`<base>`.custom" replaces the base package's same-named item whole. `basedOn` is recorded and never judged. |
108109

109110

110111
---

‎content/docs/references/automation/flow.mdx‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ const result = FlowSchema.parse(data);
5050
| **_packageId** | `string` | optional | Owning package machine id. |
5151
| **_packageVersion** | `string` | optional | Owning package version. |
5252
| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. |
53+
| **overrides** | `{ package: string; basedOn: string }` | optional | Override declaration (ADR-0146 D2): `{ package, basedOn }` — this item of "`<base>`.custom" replaces the base package's same-named item whole. `basedOn` is recorded and never judged. |
5354

5455
### Nested Shape: `Flow.variables[number]`
5556

@@ -107,6 +108,13 @@ const result = FlowSchema.parse(data);
107108
| **reason** | `string` | ✅ | User-visible reason shown when the lock blocks an action. |
108109
| **docsUrl** | `string` | optional | Optional URL the Studio banner links to for more context. |
109110

111+
### Nested Shape: `Flow.overrides`
112+
113+
| Property | Type | Required | Description |
114+
| :--- | :--- | :--- | :--- |
115+
| **package** | `string` | ✅ | The base package id whose same-named item this item replaces whole (e.g. "com.acme.crm"). Only an item of the base's paired "`<base>`.custom" package declares an override. |
116+
| **basedOn** | `string` | ✅ | Recorded, never judged: the version of the base item this override was taken from (e.g. "3.2.0"). No door compares it with the installed base, no upgrade diff is produced from it, and nothing is refused on it; it tells a person re-basing the override where it started (ADR-0146 D2). |
117+
110118

111119
---
112120

@@ -264,6 +272,7 @@ const result = FlowSchema.parse(data);
264272
| **_packageId** | `string` | optional | Owning package machine id. |
265273
| **_packageVersion** | `string` | optional | Owning package version. |
266274
| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. |
275+
| **overrides** | `{ package: string; basedOn: string }` | optional | Override declaration (ADR-0146 D2): `{ package, basedOn }` — this item of "`<base>`.custom" replaces the base package's same-named item whole. `basedOn` is recorded and never judged. |
267276

268277

269278
---

‎content/docs/references/data/mapping.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@ const result = ImportFieldMappingSchema.parse(data);
5757
| **_packageId** | `string` | optional | Owning package machine id. |
5858
| **_packageVersion** | `string` | optional | Owning package version. |
5959
| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. |
60+
| **overrides** | `{ package: string; basedOn: string }` | optional | Override declaration (ADR-0146 D2): `{ package, basedOn }` — this item of "`<base>`.custom" replaces the base package's same-named item whole. `basedOn` is recorded and never judged. |
6061

6162
### Nested Shape: `Mapping.fieldMapping[number]`
6263

@@ -77,6 +78,13 @@ const result = ImportFieldMappingSchema.parse(data);
7778
| **recordsPath** | `string` | optional | Dot path, within the action's result, to the array of records (e.g. `body.results`); omitted ⇒ the result's `body` is the array |
7879
| **watermark** | `{ field: string; param: string }` | optional | Timestamp-incremental pull; omitted ⇒ every pull reads the full set. Either way a pull makes ONE action call and reads ONE response: the connector's paging is not followed, so a paged endpoint yields its first page only — and an incremental pull over a newest-first paged endpoint moves its starting point past the pages it never read |
7980

81+
### Nested Shape: `Mapping.overrides`
82+
83+
| Property | Type | Required | Description |
84+
| :--- | :--- | :--- | :--- |
85+
| **package** | `string` | ✅ | The base package id whose same-named item this item replaces whole (e.g. "com.acme.crm"). Only an item of the base's paired "`<base>`.custom" package declares an override. |
86+
| **basedOn** | `string` | ✅ | Recorded, never judged: the version of the base item this override was taken from (e.g. "3.2.0"). No door compares it with the installed base, no upgrade diff is produced from it, and nothing is refused on it; it tells a person re-basing the override where it started (ADR-0146 D2). |
87+
8088

8189
---
8290

‎content/docs/references/data/object.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -525,6 +525,7 @@ const result = ApiMethod.parse(data);
525525
| **_packageId** | `string` | optional | Owning package machine id. |
526526
| **_packageVersion** | `string` | optional | Owning package version. |
527527
| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. |
528+
| **overrides** | `{ package: string; basedOn: string }` | optional | Override declaration (ADR-0146 D2): `{ package, basedOn }` — this item of "`<base>`.custom" replaces the base package's same-named item whole. `basedOn` is recorded and never judged. |
528529

529530
### Nested Shape: `Object.protection`
530531

‎content/docs/references/index.mdx‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Protocol reference — every schema by module
33
navTitle: Protocol Reference
4-
description: Every schema published by @objectstack/spec — 1571 schemas across 14 protocol modules
4+
description: Every schema published by @objectstack/spec — 1572 schemas across 14 protocol modules
55
---
66

77
{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
@@ -26,15 +26,15 @@ counts are sums of the rows they head. Regenerate with
2626
| [Data Protocol](/docs/references/data) | 31 | 174 | Objects, fields, queries, filters, datasources and drivers — the ObjectQL layer. |
2727
| [Identity Protocol](/docs/references/identity) | 5 | 27 | Users and accounts, organizations, positions, SCIM provisioning. |
2828
| [Integration Protocol](/docs/references/integration) | 1 | 22 | The single connector protocol (ADR-0097) — catalog descriptors and provider-bound instances. |
29-
| [Kernel Protocol](/docs/references/kernel) | 29 | 151 | Plugin lifecycle and manifests, capabilities and security, metadata loading, service registry. |
29+
| [Kernel Protocol](/docs/references/kernel) | 30 | 152 | Plugin lifecycle and manifests, capabilities and security, metadata loading, service registry. |
3030
| [Marketplace Protocol](/docs/references/marketplace) | 4 | 30 | The package & marketplace format — package identity and versions, listing, publish, review, search, install, template manifests. |
3131
| [QA Protocol](/docs/references/qa) | 1 | 8 | Declarative test suites — scenarios, steps, actions and assertions. |
3232
| [Security Protocol](/docs/references/security) | 6 | 37 | Permission sets, row-level security, sharing rules, tenancy posture. |
3333
| [Shared Protocol](/docs/references/shared) | 10 | 31 | Primitives used across every protocol — identifiers, HTTP, expressions, error maps, enums. |
3434
| [Studio Protocol](/docs/references/studio) | 3 | 35 | Studio designer metadata — the authoring surfaces for the protocols above. |
3535
| [System Protocol](/docs/references/system) | 37 | 287 | The runtime environment — logging, jobs, cache, metrics, notifications, i18n and compliance. |
3636
| [UI Protocol](/docs/references/ui) | 16 | 172 | Apps, pages, views, dashboards, reports, actions and themes — the ObjectUI layer. |
37-
| **Total** | **204** | **1571** | 14 protocol modules |
37+
| **Total** | **205** | **1572** | 14 protocol modules |
3838

3939
---
4040

@@ -204,7 +204,7 @@ The single connector protocol (ADR-0097) — catalog descriptors and provider-bo
204204

205205
## Kernel Protocol
206206

207-
**Source:** `packages/spec/src/kernel/` · **Import:** `@objectstack/spec/kernel` · **29 pages, 151 schemas**
207+
**Source:** `packages/spec/src/kernel/` · **Import:** `@objectstack/spec/kernel` · **30 pages, 152 schemas**
208208

209209
Plugin lifecycle and manifests, capabilities and security, metadata loading, service registry.
210210

@@ -225,6 +225,7 @@ Plugin lifecycle and manifests, capabilities and security, metadata loading, ser
225225
| [`metadata-loader.zod.ts`](/docs/references/kernel/metadata-loader) | `MetadataFallbackStrategy`, `MetadataManagerConfig` |
226226
| [`metadata-plugin.zod.ts`](/docs/references/kernel/metadata-plugin) | `MetadataBulkResult`, `MetadataDependency`, `MetadataPluginConfig`, `MetadataPluginManifest`, `MetadataQuery`, `MetadataQueryResult`, `MetadataType`, `MetadataTypeRegistryEntry`, `MetadataValidationResult` |
227227
| [`metadata-protection.zod.ts`](/docs/references/kernel/metadata-protection) | `MetadataLock`, `MetadataLockSource`, `MetadataProvenance` |
228+
| [`override-declaration.zod.ts`](/docs/references/kernel/override-declaration) | `OverrideDeclaration` |
228229
| [`package-artifact.zod.ts`](/docs/references/kernel/package-artifact) | `ArtifactChecksum`, `ArtifactFileEntry`, `ArtifactSignature`, `MetadataCategoryEnum`, `PackageArtifact` |
229230
| [`package-registry.zod.ts`](/docs/references/kernel/package-registry) | `DisablePackageRequest`, `DisablePackageResponse`, `EnablePackageRequest`, `EnablePackageResponse`, `GetPackageRequest`, `GetPackageResponse`, `InstallPackageRequest`, `InstallPackageResponse`, `InstalledPackage`, `InstalledPackageSource`, `ListPackagesRequest`, `ListPackagesResponse`, `NamespaceConflictError`, `NamespaceRegistryEntry`, `PackageStatusEnum`, `UninstallPackageRequest`, `UninstallPackageResponse` |
230231
| [`plugin.zod.ts`](/docs/references/kernel/plugin) | `Plugin` |

‎content/docs/references/kernel/index.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Kernel Protocol — complete schema reference
33
navTitle: Kernel Protocol
4-
description: "The ObjectStack Kernel Protocol in 29 reference pages: every schema in @objectstack/spec with its properties, types, defaults and a TypeScript example."
4+
description: "The ObjectStack Kernel Protocol in 30 reference pages: every schema in @objectstack/spec with its properties, types, defaults and a TypeScript example."
55
---
66

77
{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
@@ -24,6 +24,7 @@ This section contains all protocol schemas for the kernel layer of ObjectStack.
2424
<Card href="/docs/references/kernel/metadata-loader" title="Metadata Loader" description="Source: packages/spec/src/kernel/metadata-loader.zod.ts" />
2525
<Card href="/docs/references/kernel/metadata-plugin" title="Metadata Plugin" description="Source: packages/spec/src/kernel/metadata-plugin.zod.ts" />
2626
<Card href="/docs/references/kernel/metadata-protection" title="Metadata Protection" description="Source: packages/spec/src/kernel/metadata-protection.zod.ts" />
27+
<Card href="/docs/references/kernel/override-declaration" title="Override Declaration" description="Source: packages/spec/src/kernel/override-declaration.zod.ts" />
2728
<Card href="/docs/references/kernel/package-artifact" title="Package Artifact" description="Source: packages/spec/src/kernel/package-artifact.zod.ts" />
2829
<Card href="/docs/references/kernel/package-registry" title="Package Registry" description="Source: packages/spec/src/kernel/package-registry.zod.ts" />
2930
<Card href="/docs/references/kernel/plugin" title="Plugin" description="Source: packages/spec/src/kernel/plugin.zod.ts" />

‎content/docs/references/kernel/meta.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@
3434
"events-dlq",
3535
"events-handlers",
3636
"events-integrations",
37-
"events-queue"
37+
"events-queue",
38+
"override-declaration"
3839
]
3940
}

‎content/docs/references/kernel/metadata-plugin.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -368,6 +368,7 @@ const result = MetadataBulkResultSchema.parse(data);
368368
| **_packageId** | `string` | optional | Owning package machine id. |
369369
| **_packageVersion** | `string` | optional | Owning package version. |
370370
| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. |
371+
| **overrides** | `{ package: string; basedOn: string }` | optional | Override declaration (ADR-0146 D2): `{ package, basedOn }` — this item of "`<base>`.custom" replaces the base package's same-named item whole. `basedOn` is recorded and never judged. |
371372

372373

373374
---
Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
title: Override Declaration — Kernel Protocol
3+
navTitle: Override Declaration
4+
description: "A customization of an installed base package (HotCRM) is an item of the base's paired writable package <base>.custom."
5+
---
6+
7+
{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
8+
9+
## The override declaration (ADR-0146 D2)
10+
11+
A customization of an installed base package (HotCRM) is an item of the
12+
base's paired writable package `<base>.custom` (ADR-0146 D3). An item of that
13+
package that bears a base item's name and carries
14+
15+
```ts
16+
overrides: { package: '<base package id>', basedOn: '<the base item's version>' }
17+
```
18+
19+
replaces the base's item WHOLE for every read that serves the base's name
20+
(ADR-0146 D8). The declaration lives in the item body, so it travels with the
21+
item through export and git: what a developer writes into `hotcrm.custom` in a
22+
repository and what an administrator does in Studio produce the same
23+
document. Only the paired `<base>.custom` package declares an override (the
24+
ruling recorded on #28390, ruling A); the pairing helpers in
25+
`customization-package.ts` are what a door asks.
26+
27+
### Why a leaf module
28+
29+
It imports nothing but zod and `strictObject`, on purpose. Every overridable
30+
type's schema spreads `OverrideDeclarationFields`, and some of those
31+
schemas are imported by `manifest.zod.ts` (`ui/app.zod.ts`); importing the
32+
manifest or the registry from here would close a module cycle that the eager
33+
schema build (`OS_EAGER_SCHEMAS=1`) evaluates in temporal-dead-zone order.
34+
The helpers that need the manifest grammar live in `customization-package.ts`,
35+
which no schema imports.
36+
37+
### What this module does NOT do
38+
39+
It declares the shape. Admitting a declared override, refusing an undeclared
40+
same-named item, refusing a declaration from a package that is not the pair,
41+
and serving the declared document are the doors' (ADR-0146 Rollout, P1:
42+
the write gate, the effective read, the ensure door). Which types may carry
43+
the declaration is the closed list `OVERRIDE_TYPE_CLASSIFICATION`, never a
44+
judgement a door makes.
45+
46+
<Callout type="info">
47+
**Source:** `packages/spec/src/kernel/override-declaration.zod.ts`
48+
</Callout>
49+
50+
## TypeScript Usage
51+
52+
```typescript
53+
import { OverrideDeclarationSchema } from '@objectstack/spec/kernel';
54+
import type { OverrideDeclaration } from '@objectstack/spec/kernel';
55+
56+
// Validate data
57+
const result = OverrideDeclarationSchema.parse(data);
58+
```
59+
60+
---
61+
62+
## OverrideDeclaration
63+
64+
Override declaration (ADR-0146 D2): this item, of the base's paired "`<base>`.custom" package and bearing a base item's name, replaces that base item whole for every read that serves the name.
65+
66+
### Properties
67+
68+
| Property | Type | Required | Description |
69+
| :--- | :--- | :--- | :--- |
70+
| **package** | `string` | ✅ | The base package id whose same-named item this item replaces whole (e.g. "com.acme.crm"). Only an item of the base's paired "`<base>`.custom" package declares an override. |
71+
| **basedOn** | `string` | ✅ | Recorded, never judged: the version of the base item this override was taken from (e.g. "3.2.0"). No door compares it with the installed base, no upgrade diff is produced from it, and nothing is refused on it; it tells a person re-basing the override where it started (ADR-0146 D2). |
72+
73+
74+
---
75+

0 commit comments

Comments
 (0)