Skip to content

Commit d127ff0

Browse files
os-zhuangclaude
os-zhuang
and
claude
authored
refactor(spec): rename ./system ServiceStatus to KernelServiceStatus (#6604) (#7240)
`ServiceStatus` was published by two entry points for two disjoint concepts: `./api`'s discovery health enum and `./system`'s kernel service state object. Per the maintainer's 2026-08-08 Option-B ruling the kernel side takes the domain-specific name, matching its `KernelServiceMapSchema` sibling, and `./api` keeps its published name untouched. This is what finally lets `./system` declare the `KernelServiceStatus` type alias #4593's backfill had to skip: declaring `ServiceStatus` on both entry points would have minted the #4411 dual-source trap that `dual-source-exports.baseline.json` stays empty to prevent. Routed through `RENAMED_DEFS` rather than the retirement kit — all 6 authorable keys carry, so nothing left the author-facing contract. Claude-Session: https://claude.ai/code/session_01PiRUoQkTSBBmpyXBY3cVn2 Co-authored-by: Claude <noreply@anthropic.com>
1 parent 9a528f5 commit d127ff0

13 files changed

Lines changed: 132 additions & 44 deletions

File tree

‎.changeset/kernel-service-status-dual-source.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
"@objectstack/spec": minor
3+
---
4+
5+
BREAKING(spec): `@objectstack/spec/system` renames `ServiceStatusSchema` → `KernelServiceStatusSchema` and gains the `KernelServiceStatus` type alias (#6604, ADR-0112 D9a)
6+
7+
`ServiceStatus` was published by two entry points for two disjoint concepts: `./api`'s
8+
discovery health **enum** (`api/discovery.zod.ts`) and `./system`'s kernel service **state
9+
object** (`system/core-services.zod.ts`, a `features`-bearing record). Per the maintainer
10+
ruling of 2026-08-08 (Option B) the kernel side takes the domain-specific name, matching
11+
its `KernelServiceMapSchema` sibling in the same file:
12+
13+
- `ServiceStatusSchema` → `KernelServiceStatusSchema` (`@objectstack/spec/system`)
14+
- new: `export type KernelServiceStatus` — the alias `#4593`'s backfill had to skip,
15+
because declaring `ServiceStatus` on both entry points would have minted the #4411
16+
dual-source trap
17+
- JSON Schema def `system/ServiceStatus` → `system/KernelServiceStatus`, carried through
18+
`RENAMED_DEFS` with all 6 authorable keys (`enabled` / `features` / `name` / `provider` /
19+
`status` / `version`) intact
20+
21+
**`@objectstack/spec/api`'s `ServiceStatus` is untouched** — it keeps its published name,
22+
so no consumer of the discovery health enum changes. Nothing left the author-facing
23+
contract: the renamed def re-emits every key byte-for-byte, which is why this rides the
24+
rename table rather than the retirement kit. Consumers importing `ServiceStatusSchema`
25+
from `@objectstack/spec/system` update the name; `tsc` reports TS2724/TS2305 on any that
26+
does not.

‎content/docs/references/index.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -330,7 +330,7 @@ The runtime environment — logging, jobs, cache, metrics, notifications, i18n a
330330
| [`cache.zod.ts`](/docs/references/system/cache) | `CacheAvalanchePrevention`, `CacheConfig`, `CacheConsistency`, `CacheInvalidation`, `CacheStrategy`, `CacheTier`, `CacheWarmup`, `DistributedCacheConfig` |
331331
| [`change-management.zod.ts`](/docs/references/system/change-management) | `ChangeImpact`, `ChangePriority`, `ChangeRequest`, `ChangeStatus`, `ChangeType`, `RollbackPlan` |
332332
| [`collaboration.zod.ts`](/docs/references/system/collaboration) | `AwarenessEvent`, `AwarenessSession`, `AwarenessUpdate`, `AwarenessUserState`, `CRDTMergeResult`, `CRDTState`, `CRDTType`, `CollaborationMode`, `CollaborationSession`, `CollaborationSessionConfig`, `CollaborativeCursor`, `CounterOperation`, `CursorColorPreset`, `CursorSelection`, `CursorStyle`, `CursorUpdate`, `GCounter`, `LWWRegister`, `ORSet`, `ORSetElement`, `OTComponent`, `OTOperation`, `OTOperationType`, `OTTransformResult`, `PNCounter`, `TextCRDTOperation`, `TextCRDTState`, `UserActivityStatus`, `VectorClock` |
333-
| [`core-services.zod.ts`](/docs/references/system/core-services) | `CoreServiceName`, `KernelServiceMap`, `ServiceConfig`, `ServiceCriticality`, `ServiceStatus` |
333+
| [`core-services.zod.ts`](/docs/references/system/core-services) | `CoreServiceName`, `KernelServiceMap`, `KernelServiceStatus`, `ServiceConfig`, `ServiceCriticality` |
334334
| [`deploy-bundle.zod.ts`](/docs/references/system/deploy-bundle) | `DeployBundle`, `DeployDiff`, `DeployManifest`, `DeployStatusEnum`, `DeployValidationIssue`, `DeployValidationResult`, `MigrationPlan`, `MigrationStatement`, `SchemaChange` |
335335
| [`disaster-recovery.zod.ts`](/docs/references/system/disaster-recovery) | `BackupConfig`, `BackupRetention`, `BackupStrategy`, `DisasterRecoveryPlan`, `FailoverConfig`, `FailoverMode`, `RPO`, `RTO` |
336336
| [`doc.zod.ts`](/docs/references/system/doc) | `Doc` |

‎content/docs/references/system/core-services.mdx‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,8 @@ This registry is used by the `ObjectKernel` and `HttpDispatcher` to:
2020
## TypeScript Usage
2121

2222
```typescript
23-
import { CoreServiceName, KernelServiceMapSchema, ServiceConfigSchema, ServiceCriticalitySchema, ServiceStatusSchema } from '@objectstack/spec/system';
24-
import type { CoreServiceName, KernelServiceMap, ServiceConfig, ServiceCriticality } from '@objectstack/spec/system';
23+
import { CoreServiceName, KernelServiceMapSchema, KernelServiceStatusSchema, ServiceConfigSchema, ServiceCriticalitySchema } from '@objectstack/spec/system';
24+
import type { CoreServiceName, KernelServiceMap, KernelServiceStatus, ServiceConfig, ServiceCriticality } from '@objectstack/spec/system';
2525

2626
// Validate data
2727
const result = CoreServiceName.parse(data);
@@ -53,6 +53,22 @@ const result = CoreServiceName.parse(data);
5353
---
5454

5555

56+
---
57+
58+
## KernelServiceStatus
59+
60+
### Properties
61+
62+
| Property | Type | Required | Description |
63+
| :--- | :--- | :--- | :--- |
64+
| **name** | `Enum<'metadata' \| 'data' \| 'auth' \| 'file-storage' \| 'search' \| 'cache' \| 'queue' \| 'automation' \| 'analytics' \| 'realtime' \| 'job' \| 'notification' \| 'ai' \| 'i18n' \| 'ui'>` | ✅ | |
65+
| **enabled** | `boolean` | ✅ | |
66+
| **status** | `Enum<'running' \| 'stopped' \| 'degraded' \| 'initializing'>` | ✅ | |
67+
| **version** | `string` | optional | |
68+
| **provider** | `string` | optional | Implementation provider (e.g. "s3" for storage) |
69+
| **features** | `string[]` | optional | List of supported sub-features |
70+
71+
5672
---
5773

5874
## ServiceConfig
@@ -79,19 +95,3 @@ const result = CoreServiceName.parse(data);
7995

8096
---
8197

82-
## ServiceStatus
83-
84-
### Properties
85-
86-
| Property | Type | Required | Description |
87-
| :--- | :--- | :--- | :--- |
88-
| **name** | `Enum<'metadata' \| 'data' \| 'auth' \| 'file-storage' \| 'search' \| 'cache' \| 'queue' \| 'automation' \| 'analytics' \| 'realtime' \| 'job' \| 'notification' \| 'ai' \| 'i18n' \| 'ui'>` | ✅ | |
89-
| **enabled** | `boolean` | ✅ | |
90-
| **status** | `Enum<'running' \| 'stopped' \| 'degraded' \| 'initializing'>` | ✅ | |
91-
| **version** | `string` | optional | |
92-
| **provider** | `string` | optional | Implementation provider (e.g. "s3" for storage) |
93-
| **features** | `string[]` | optional | List of supported sub-features |
94-
95-
96-
---
97-

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -291,6 +291,8 @@
291291
"JobSchema (const)",
292292
"KernelServiceMap (type)",
293293
"KernelServiceMapSchema (const)",
294+
"KernelServiceStatus (type)",
295+
"KernelServiceStatusSchema (const)",
294296
"KeyManagementProvider (type)",
295297
"KeyManagementProviderSchema (const)",
296298
"KeyRotationPolicy (type)",
@@ -573,7 +575,6 @@
573575
"ServiceLevelObjectiveParsed (type)",
574576
"ServiceLevelObjectiveSchema (const)",
575577
"ServiceRequirementDef (const)",
576-
"ServiceStatusSchema (const)",
577578
"SettingsActionResult (type)",
578579
"SettingsActionResultSchema (const)",
579580
"SettingsChangeEvent (type)",

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -540,6 +540,12 @@
540540
"system/JobExecution:jobId",
541541
"system/JobExecution:startedAt",
542542
"system/JobExecution:status",
543+
"system/KernelServiceStatus:enabled",
544+
"system/KernelServiceStatus:features",
545+
"system/KernelServiceStatus:name",
546+
"system/KernelServiceStatus:provider",
547+
"system/KernelServiceStatus:status",
548+
"system/KernelServiceStatus:version",
543549
"system/KeyRotationPolicy:autoRotate",
544550
"system/KeyRotationPolicy:enabled",
545551
"system/KeyRotationPolicy:frequencyDays",
@@ -1051,12 +1057,6 @@
10511057
"system/ServiceLevelObjective:period",
10521058
"system/ServiceLevelObjective:sli",
10531059
"system/ServiceLevelObjective:target",
1054-
"system/ServiceStatus:enabled",
1055-
"system/ServiceStatus:features",
1056-
"system/ServiceStatus:name",
1057-
"system/ServiceStatus:provider",
1058-
"system/ServiceStatus:status",
1059-
"system/ServiceStatus:version",
10601060
"system/SettingsActionResult:details",
10611061
"system/SettingsActionResult:message",
10621062
"system/SettingsActionResult:ok",

‎packages/spec/docs-import-surface.baseline.json‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,6 @@
4242
"system/AddFieldOperation — no type export",
4343
"system/CreateObjectOperation — no type export",
4444
"system/DeployStatusEnum — no type export",
45-
"system/ServiceStatus — no type export",
4645
"ui/AIChatWindowProps — no type export",
4746
"ui/DerivedMeasureOp — no type export",
4847
"ui/ElementButtonProps — no type export",

‎packages/spec/export-origins/system.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -291,6 +291,8 @@
291291
"JobSchema": "src/system/job.zod.ts#JobSchema (const)",
292292
"KernelServiceMap": "src/system/core-services.zod.ts#KernelServiceMap (type)",
293293
"KernelServiceMapSchema": "src/system/core-services.zod.ts#KernelServiceMapSchema (const)",
294+
"KernelServiceStatus": "src/system/core-services.zod.ts#KernelServiceStatus (type)",
295+
"KernelServiceStatusSchema": "src/system/core-services.zod.ts#KernelServiceStatusSchema (const)",
294296
"KeyManagementProvider": "src/system/encryption.zod.ts#KeyManagementProvider (type)",
295297
"KeyManagementProviderSchema": "src/system/encryption.zod.ts#KeyManagementProviderSchema (const)",
296298
"KeyRotationPolicy": "src/system/encryption.zod.ts#KeyRotationPolicy (type)",
@@ -573,7 +575,6 @@
573575
"ServiceLevelObjectiveParsed": "src/system/metrics.zod.ts#ServiceLevelObjectiveParsed (type)",
574576
"ServiceLevelObjectiveSchema": "src/system/metrics.zod.ts#ServiceLevelObjectiveSchema (const)",
575577
"ServiceRequirementDef": "src/system/core-services.zod.ts#ServiceRequirementDef (const)",
576-
"ServiceStatusSchema": "src/system/core-services.zod.ts#ServiceStatusSchema (const)",
577578
"SettingsActionResult": "src/system/settings-manifest.zod.ts#SettingsActionResult (type)",
578579
"SettingsActionResultSchema": "src/system/settings-manifest.zod.ts#SettingsActionResultSchema (const)",
579580
"SettingsChangeEvent": "src/system/settings-client.zod.ts#SettingsChangeEvent (type)",

‎packages/spec/json-schema.manifest/system.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,7 @@
115115
"system/JobExecution",
116116
"system/JobExecutionStatus",
117117
"system/KernelServiceMap",
118+
"system/KernelServiceStatus",
118119
"system/KeyManagementProvider",
119120
"system/KeyRotationPolicy",
120121
"system/LWWRegister",
@@ -222,7 +223,6 @@
222223
"system/ServiceCriticality",
223224
"system/ServiceLevelIndicator",
224225
"system/ServiceLevelObjective",
225-
"system/ServiceStatus",
226226
"system/SettingsActionResult",
227227
"system/SettingsChangeEvent",
228228
"system/SettingsManifest",

‎packages/spec/scripts/lib/renamed-defs.ts‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,30 @@ export const RENAMED_DEFS: Readonly<Record<string, string>> = {
137137
// always had), which no ratchet here measures and which the changeset states.
138138
// `shared/HttpMethodSubset` is a plain manifest addition.
139139
'ui/HttpMethod': 'ui/HttpMethodSubset',
140+
141+
// #6604 / ADR-0112 D9a — `ServiceStatus` was published by `./api` AND
142+
// `./system` for two disjoint concepts: the discovery HEALTH ENUM
143+
// (`api/discovery.zod.ts`, `z.enum(['operational', ...])`) and the kernel
144+
// service STATE OBJECT (`system/core-services.zod.ts`, a `features`-bearing
145+
// record). Maintainer ruling 2026-08-08 (Option B): the kernel side is
146+
// renamed and `./api` keeps the published bare name untouched — the smallest
147+
// blast radius, because the system side had no type alias yet, so the name
148+
// had not petrified there.
149+
//
150+
// 6 keys carried (`enabled` / `features` / `name` / `provider` / `status` /
151+
// `version`) — every one of them re-emitted byte-for-byte under the new def,
152+
// which is the whole point of routing this through the table rather than the
153+
// retirement kit: NOTHING left the author-facing contract. `api/ServiceStatus`
154+
// is deliberately absent — it is still emitted, by the enum that always
155+
// declared it, so the table would (correctly) reject it as a copy.
156+
//
157+
// This entry is what finally lets the `./system` side declare
158+
// `KernelServiceStatus`: #4593's alias backfill had to skip this one name
159+
// because declaring `ServiceStatus` on both entry points would have minted
160+
// the #4411 dual-source trap `dual-source-exports.baseline.json` stays empty
161+
// to prevent. The rename removes the collision at its source, so the baseline
162+
// stays empty rather than gaining its first exception.
163+
'system/ServiceStatus': 'system/KernelServiceStatus', // 6 keys carried
140164
};
141165

142166
/**

‎packages/spec/scripts/schema-index.test.ts‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -97,11 +97,19 @@ describe('exportedValueNames', () => {
9797
});
9898

9999
describe('buildSchemaIndex — cross-category same name', () => {
100-
// The live specimen on `main`: `ServiceStatus` is an enum declared in
101-
// `api/discovery.zod.ts` AND an object declared in
100+
// Drawn from the live specimen this behaviour was found on: `ServiceStatus`
101+
// was an enum declared in `api/discovery.zod.ts` AND an object declared in
102102
// `system/core-services.zod.ts`. The bare-name index let `system` (walked
103103
// later) win, and then placed the API schema on `api/core-services.mdx` —
104104
// a page with no `api/core-services.zod.ts` behind it.
105+
//
106+
// That specimen is no longer live: #6604 renamed the system side to
107+
// `KernelServiceStatusSchema`, so the two categories no longer publish the
108+
// name. The fixture stays SYNTHETIC and unchanged on purpose — what it pins
109+
// is that cross-category same-name resolution is correct whenever it occurs,
110+
// and a rename of one specimen retires the specimen, not the property. Wiring
111+
// the fixture to whatever names happen to collide on `main` today would make
112+
// this coverage evaporate the next time someone tidies those names up.
105113
const idx = index(
106114
file('api', 'discovery.zod.ts', 'export const ServiceStatus = z.enum([]);'),
107115
file('system', 'core-services.zod.ts', 'export const ServiceStatusSchema = z.object({});'),

0 commit comments

Comments
 (0)