Repository navigation
Patch release 0.7.2: System protocol schemas and documentation - #444
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
|
This PR is very large. Consider breaking it into smaller PRs for easier review. |
There was a problem hiding this comment.
Pull request overview
Prepares the 0.7.2 patch release by adding/generated JSON Schema artifacts for system protocols and updating reference documentation + release metadata.
Changes:
- Added/generated JSON Schemas for system protocols (events + worker/task-related schemas).
- Refactored several system reference docs into schema-first reference pages and updated navigation.
- Added a changeset for patch bumps and updated the root CHANGELOG for 0.7.2.
Reviewed changes
Copilot reviewed 41 out of 41 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/spec/json-schema/system/WorkerStats.json | Adds JSON Schema for worker runtime statistics. |
| packages/spec/json-schema/system/WorkerConfig.json | Adds JSON Schema for worker configuration (queues, limits, handlers). |
| packages/spec/json-schema/system/TaskStatus.json | Adds TaskStatus enum JSON Schema. |
| packages/spec/json-schema/system/TaskRetryPolicy.json | Adds TaskRetryPolicy JSON Schema. |
| packages/spec/json-schema/system/TaskPriority.json | Adds TaskPriority enum JSON Schema. |
| packages/spec/json-schema/system/TaskExecutionResult.json | Adds JSON Schema describing task execution results. |
| packages/spec/json-schema/system/Task.json | Adds JSON Schema for task objects (payload, scheduling, retries). |
| packages/spec/json-schema/system/RealTimeNotificationConfig.json | Adds JSON Schema for realtime event notification settings. |
| packages/spec/json-schema/system/QueueConfig.json | Adds JSON Schema for queue configuration (rate limits, autoscale, etc.). |
| packages/spec/json-schema/system/EventWebhookConfig.json | Adds JSON Schema for event webhooks configuration. |
| packages/spec/json-schema/system/EventTypeDefinition.json | Adds JSON Schema for event type registry entries. |
| packages/spec/json-schema/system/EventSourcingConfig.json | Adds JSON Schema for event sourcing settings. |
| packages/spec/json-schema/system/EventReplayConfig.json | Adds JSON Schema for event replay settings. |
| packages/spec/json-schema/system/EventQueueConfig.json | Adds JSON Schema for event queue settings. |
| packages/spec/json-schema/system/EventPriority.json | Adds EventPriority enum JSON Schema. |
| packages/spec/json-schema/system/EventPersistence.json | Extends persistence schema (adds storage backend enum). |
| packages/spec/json-schema/system/EventMetadata.json | Extends event metadata schema (correlation/causation/priority). |
| packages/spec/json-schema/system/EventMessageQueueConfig.json | Adds JSON Schema for MQ publishing integration. |
| packages/spec/json-schema/system/EventLogEntry.json | Adds JSON Schema for persisted/observed event log entries. |
| packages/spec/json-schema/system/EventHandler.json | Extends event handler schema (adds id + retry policy). |
| packages/spec/json-schema/system/EventBusConfig.json | Adds comprehensive JSON Schema for event bus configuration. |
| packages/spec/json-schema/system/Event.json | Extends event schema (adds id + metadata additions). |
| packages/spec/json-schema/system/DeadLetterQueueEntry.json | Adds JSON Schema for DLQ entries. |
| packages/spec/json-schema/system/BatchTask.json | Adds JSON Schema for batch task definitions. |
| packages/spec/json-schema/system/BatchProgress.json | Adds JSON Schema for batch progress reporting. |
| content/docs/references/system/startup-orchestrator.mdx | Rewrites doc to schema-focused reference format. |
| content/docs/references/system/service-registry.mdx | Rewrites doc to schema-focused reference format. |
| content/docs/references/system/plugin-validator.mdx | Rewrites doc to schema-focused reference format. |
| content/docs/references/system/plugin-lifecycle-events.mdx | Updates schema-focused reference formatting and expands schema listing. |
| content/docs/references/system/metadata-loader.mdx | Rewrites doc to schema-focused reference format and expands schema listing. |
| content/docs/references/system/meta.json | Updates system docs sidebar/navigation entries (adds worker). |
| content/docs/references/system/index.mdx | Updates system docs landing page cards (adds worker). |
| content/docs/references/system/events.mdx | Expands events reference doc with new related schemas and properties. |
| content/docs/references/integration/meta.json | Removes connector-file-storage page from integration docs navigation. |
| content/docs/references/integration/connector-file-storage.mdx | Deletes the File Storage Connector reference page. |
| content/docs/references/data/meta.json | Removes driver-mongo and driver-postgres pages from data docs navigation. |
| content/docs/references/data/driver-postgres.mdx | Deletes PostgreSQL driver reference page. |
| content/docs/references/data/driver-mongo.mdx | Deletes MongoDB driver reference page. |
| content/docs/references/automation/connector.mdx | Updates the Connector reference page source/import paths (currently incorrect). |
| CHANGELOG.md | Adds 0.7.2 release entry and updates compare links. |
| .changeset/patch-release.md | Adds patch changeset for version bumps across packages. |
| <Callout type="info"> | ||
| **Source:** `packages/spec/src/integration/connector.zod.ts` | ||
| **Source:** `packages/spec/src/automation/connector.zod.ts` | ||
| </Callout> | ||
|
|
||
| ## TypeScript Usage | ||
|
|
||
| ```typescript | ||
| import { AuthenticationSchema, ConflictResolutionSchema, ConnectorSchema, DataSyncConfigSchema } from '@objectstack/spec/integration'; | ||
| import type { Authentication, ConflictResolution, Connector, DataSyncConfig } from '@objectstack/spec/integration'; | ||
| import { AuthenticationSchema, ConflictResolutionSchema, ConnectorSchema, DataSyncConfigSchema } from '@objectstack/spec/automation'; | ||
| import type { Authentication, ConflictResolution, Connector, DataSyncConfig } from '@objectstack/spec/automation'; |
There was a problem hiding this comment.
This reference page points to packages/spec/src/automation/connector.zod.ts and imports from @objectstack/spec/automation, but there is no src/automation/connector.zod.ts and automation/index.ts does not export a Connector protocol. The Connector protocol currently lives in packages/spec/src/integration/connector.zod.ts and should be referenced/imported from @objectstack/spec/integration instead (or add the missing automation schema + exports if the move was intended).
| "durationMs": { | ||
| "type": "integer", | ||
| "description": "Execution duration in milliseconds" | ||
| }, |
There was a problem hiding this comment.
durationMs represents an execution duration, but the schema allows negative values because it has no minimum. Consider adding minimum: 0 (and updating the source Zod schema so regenerated JSON Schema stays in sync).
| --- | ||
| "@objectstack/spec": patch | ||
| "@objectstack/core": patch | ||
| "@objectstack/types": patch | ||
| "@objectstack/objectql": patch | ||
| "@objectstack/runtime": patch | ||
| "@objectstack/client": patch |
There was a problem hiding this comment.
PR description says “All packages bump to 0.7.2 via changeset”, but this changeset does not include @objectstack/metadata (which still exists as a package). Either include it here or adjust the PR description/release plan so versions stay consistent across packages.
| <Card href="./startup-orchestrator" title="Startup Orchestrator" description="Source: packages/spec/src/system/startup-orchestrator.zod.ts" /> | ||
| <Card href="./tracing" title="Tracing" description="Source: packages/spec/src/system/tracing.zod.ts" /> | ||
| <Card href="./translation" title="Translation" description="Source: packages/spec/src/system/translation.zod.ts" /> | ||
| <Card href="./worker" title="Worker" description="Source: packages/spec/src/system/worker.zod.ts" /> |
There was a problem hiding this comment.
The System docs index now links to a ./worker page, but there is no corresponding content/docs/references/system/worker.mdx in the repo. This will create a broken link in the docs navigation. Add the missing Worker reference page (and ensure it’s included in the build) or remove this card entry.
| <Card href="./worker" title="Worker" description="Source: packages/spec/src/system/worker.zod.ts" /> |
| "translation", | ||
| "worker" |
There was a problem hiding this comment.
"worker" was added to the System docs sidebar pages list, but the content/docs/references/system/worker.mdx page does not exist. This will break the generated navigation/route. Add the missing page or remove this entry.
| "translation", | |
| "worker" | |
| "translation" |
…e each decision in words instead of a tracker number (stage 1) (objectstack-ai#21172) Part of objectstack-ai#20752 Clause-②: no **Stage 1 of 5 of the `domain:cli` lane under the maintainer's A / A ruling (5902360492): the CLI, `cloud-connection` and `types` strings.** The card stays open for stages 2-5, so this PR carries no closing keyword. Text only: no exit code, error `code`, flag, field, HTTP status, export or control flow moves. ## What this does CLI help text, warnings, refusals and two harness errors sent the reader to a tracker number for the reason behind them. In form D, as the stages of the engine lane applied it, the number goes. Where the sentence already said what was decided, only the citation goes. Where it leaned on the number, it now says the decision in words. | Where (head line) | Cited | The text now says | |---|---|---| | `compile.ts:753`, `validate.ts:689` step line | 3366 | "Checking that every required capability has a provider installable in this edition..." | | `compile.ts:824` warning header | 3786 | "Undeclared authoring keys (N) — dropped at load; reported here, never refused" (the disposition commit 8186a70 chose: the schemas stay non-strict, the drop is reported, never fatal) | | `db/clean.ts:33` `--database` help | 6469 | "...then the one project database that os dev, os start and os migrate all resolve" | | `doctor.ts:1406` retired-key row | 2377 | "`referenceFilters` was removed from FieldSchema as a key no runtime read (ADR-0049 enforce-or-remove)" | | `meta/resync.ts:71` skip explanation | 8692 (404) | "on installs created before the seeder began stamping its default sets 'platform'" (commit 712e185: the seeder stamps `managed_by: 'platform'`, forward only) | | `meta/resync.ts:104` command description | 2705 | "(default permission sets, which boot seeds insert-once)" | | `migrate/duplicates.ts:859` description | 8725 | "...index tightenings, which os migrate plan does not report" (ruling 5377374267: the report lands here, plan's drift contract untouched) | | `migrate/duplicates.ts:861` description | 8686 | "Run it BEFORE the boot-time backfill that stamps untenanted seed rows with the install's organization" (ruling 5299880350) | | `migrate/multi-value-columns.ts:332` description | 11535 | "boot and os migrate plan only report such a column and never alter it unattended" (route C, recorded in 5405686794) | | `migrate/recorded-by.ts:69` description | 4556 | "...to NULL, the value a system-initiated write stores now" (ruling recorded in 5161102937) | | `migrate/summary-nulls.ts:81` description | 5749 | "...the insert-time seed, which now writes 0 for an empty child set" (5206990154) | | `serve.ts:4393` no-auth refusal | 3963 | "anonymous access to object data is always denied, with no setting that turns that off" | | `serve.ts:5953` organizations remedy | 4719 | "...deliberately not enough: accepting it made this wall depend on how the process was launched." | | `storage/orphans.ts:173` closing line | 10950 | "Reclaiming these bytes was decided against: deletes no longer strand files, and files stranded before that fix are left in place." (ruling 5386673556, closed not planned; the old line still called it a deferred decision) | | `test/helpers/serve-process.ts:569` harness error | 13062 | "...the port `serve.ts` PUBLISHES, which must be the port it BOUND, so this is a regression" | | `cloud-connection-route-ledger.ts:205/228/238/248` notes | 8976 | "`manage_metadata`, never merely a signed-in session" (commit e0695b5 dropped the any-session gate) | | `cloud-connection-route-ledger.ts:215` note | 9011 (404) | "`installedBy` / `storageDir` (a user id and a host filesystem path) are served only to a `manage_metadata` holder" (commit 01074e5) | | `cloud-connection-route-ledger.ts:264` note | 11863 | "a route and takes a ledger row, as trigger-api's host-mounted hook route does" | | `types/src/node.ts:383` undeclared-package note | 10943 (404) | "...passes its own `fallbackImport`, so the fallback resolves from the caller instead" (commit 46d34ab) | Citation only (the sentence already stated the decision): `dev.ts:233` (5148), `doctor.ts:221` (5673), `doctor.ts:1544` (5397), `migrate/duplicates.ts:858` (8928: the third sentence already says it never rewrites), `serve.ts:6021` (4818), `storage-driver.ts:149` and `:349` (3276), `serve-process.ts:546` (12525), `node.ts:393` (4719). Every cited card was read (REST, open or closed) before its string was rewritten. Three answer 404: 8692, 9011 and 10943. They were read through their landing commits (712e185, 01074e5, 46d34ab) and today's docblocks. ## Three ledger entries that were not tracker numbers `serve.ts` carried `objectstack-ai#111`, `objectstack-ai#666` and `objectstack-ai#444`: the 3-digit CSS colours of the unknown-hostname 404 page, the false-positive family the gate's own docblock names. They now read `#111111`, `#666666` and `#444444`, the remedy that docblock prescribes. The page renders the same. ## The source-hash header producer (patch round under claim amendment `5931899236`) `packages/cli/src/utils/i18n-extract.ts:2354` held the last two of the stage's occurrences (`objectstack-ai#12069`, `objectstack-ai#8765`). That literal is the header `renderSourceHashModule` writes as line 8 of every `LOCALE.source-hashes.generated.ts`. The seat carried it in this stage, answer A to the first report's open question. - **The rewrite, commit `d60b295649`:** the header now states what the two rulings decided, applied to the generated half. A leaf whose digest no longer matches its source is stale and serves the source text instead. The commit sha `09b4f4e4e` stays as provenance. - **The regeneration, commit `9d5f33f929`:** the 27 companions in 9 packages were regenerated with `node scripts/check-i18n-bundles.mjs --write`, never by hand. - The diff has exactly 27 files, one `@@ -8 +8 @@` hunk each, +27 / −27, with one distinct removed line and one distinct added line. - Every hash entry is byte-identical. - `check:i18n`: 9 packages in sync. `check:i18n-stale-fill`: no new stale fills. - **None of the 9 packages publishes the header:** 0 hits for the old or new header text in each package's `dist`, against a positive control of 2 to 8. So they take no changeset. `@objectstack/cli` ships the literal, and its existing `patch` changeset covers it. ## Re-pins - `meta/resync-skip-explanation.test.ts:44` asserted `objectstack-ai#8692`. It now asserts "before the seeder began stamping its default sets 'platform'". Ablation on the committed head (`scripts/ablation-replace.mjs`, WRAP mode): with that phrase replaced in `resync.ts` the file gave 1 failed / 6 passed; after the restore the blob matched HEAD (`a16ba21993`) and `git diff HEAD` was empty. - `test/build-json-undeclared-key-parity.e2e.test.ts:288` asserted the `(objectstack-ai#3786)` header. It now asserts the new header. Ablation: the first attempt used a replacement that was a substring of the anchor, and the tool refused it before running anything (count 2 → 2). The second, with a distinct marker, gave 1 failed / 5 passed. The restore matched HEAD (`7d24c878b8`) with `git diff HEAD` empty. The docblock transcript at line 12 keeps the old text, because it records a measurement at `4ceae8ab0`. - Neither pin was deleted. The test titles in test files that cite numbers are not ledgered and were left alone. ## Ledger (`scripts/doc-authoring-prose-id.baseline.json`) Recomputed with `node scripts/check-doc-authoring.mjs --census-ledger` (exit 0, no growth refusal) into a scratch file, then copied into place. The diff deletes 63 lines and adds none. Every row outside the three packages is byte-identical. After merging `origin/main` (`e35c40a525`) the recomputed ledger was byte-identical to the committed one. | | before (`fde553c509`) | after | |---|---|---| | `packages/cli` | 29 in 15 files | 0 | | `packages/cloud-connection` | 6 in 1 file | 0 | | `packages/types` | 2 in 1 file | 0 | | **three packages** | **37 in 17 files** | **0** | | whole ledger | 621 occurrences, 428 pairs, 169 files | 584 occurrences, 395 pairs, 152 files | `pnpm check:doc-authoring`: before, "521 pinned site(s) across 169 file(s) ... no growth, no burn-down unrecorded"; after the first round, "488 pinned site(s) across 153 file(s)"; after the patch round, at `9d5f33f929`, "487 pinned site(s) across 152 file(s) ... no growth, no burn-down unrecorded". The patch round's ledger diff deletes 4 lines (the `i18n-extract.ts` row) and adds none. ## Changeset `.changeset/20752-cli-strings-state-the-decision.md`: `patch` for `@objectstack/cli` and `@objectstack/types`. There is **no `@objectstack/cloud-connection` entry**, because the route ledger is not published. It is package-internal guard data that `index.ts` does not import. Measured after the build: "never merely a signed-in session" and `CLOUD_CONNECTION_ROUTE_LEDGER` are each in 0 files under `packages/cloud-connection/dist`, while the positive control `install-local` is in 6. The same measurement on `@objectstack/cli`: each new sentence is in `dist`, each old one (`capability providers (objectstack-ai#3366)`, `dropped at load (objectstack-ai#3786)`, `see issue objectstack-ai#10950`, `always denied (objectstack-ai#3963)`, `color: objectstack-ai#666;`) is in 0 files. `test/helpers/serve-process.ts` is not in `dist`. ## Text-only proof A TypeScript-AST skeleton of each changed `.ts` file compares `fde553c509` with `2ef3c98a9d`. In the skeleton every string literal and template text is one placeholder, consecutive literal operands of a `+` chain merge, and comments are never read. Result: 18 of 18 SAME, with token and literal-slot counts identical per file. Control: the same tool reports DIFF on `cli/src/utils/schema-migrate.ts` across `f20f669e17`, a real code change. ## Tests - Build: `turbo run build` over `./packages/*` and `./packages/*/*` under the verify lock, 71/71, before and again after the merge. - `@objectstack/cli` unit tier: 242 files / 3,435 tests passed, before and after the merge. `typecheck` exit 0, including `check:test-typecheck`. - `@objectstack/cli` integration tier (owed because the diff touches `test/helpers/serve-process.ts`): 69 files / 599 passed, 1 skipped, on `2ef3c98a9d`. Not re-run after the merge; the merge brings `start.ts` and a nightly e2e file, neither touching these strings. - Nightly tier (`OS_TEST_TIERS=nightly`), the two e2e files that assert the changed strings: `build-json-undeclared-key-parity.e2e.test.ts` and `serve-port-readback.e2e.test.ts`, 19/19 passed. - `@objectstack/types`: 23 files / 692 tests; `@objectstack/cloud-connection`: 30 files / 397 tests (the route-ledger conformance guard included); both `typecheck` exit 0. ## Gates `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands` (no paths) at `c023fa0d00` derived 73 commands. All 73 ran one at a time from the worktree, each exit 0. `--ran` reports "73 derived famil(ies) accounted for — 73 run, 0 NOT-MEASURED". Among them: `check:doc-authoring` (above), `check:i18n` (9 packages in sync), `check:issue-citations`, `check:nul-bytes`, `check:dts-closure` (71 packages swept) and `check:dual-build-cjs-loads`. Narrowed lint: `eslint --no-inline-config --format json` over the 18 changed `.ts` files reported 18 files, 0 errors, 0 warnings (counts from eslint's JSON). The resolved `parserOptions` are `ecmaVersion: latest, sourceType: module`, with no `project` or `projectService`, so no type-aware rule runs and this diff cannot move an untouched file's verdict. Repo-wide `pnpm lint` is CI's. NOT MEASURED locally (CI's): the Test Core shards, Dogfood, Build Core and the workspace type-check lanes. The integration tier was not re-run on the merge commit. ## Acceptance notes - **Docs transcripts that quoted the old step line** now show the new text, byte-identical to the `printStep` argument in `compile.ts` and `validate.ts`, in the patch round (`d60b295649`): `content/docs/deployment/cli.mdx:608`, `content/docs/deployment/validating-metadata.mdx:699` and `content/docs/ui/react-pages.mdx:393`. - `check:docs-transcript-drift` passes. - PR objectstack-ai#21167 also edits `cli.mdx`, around line 1485 and later, so the hunks are disjoint. - `docs/audits/...` is a dated record and stays. - `packages/cli/CHANGELOG.md` quotes old lines in released entries. That file is release-owned and untouched. - Code comments and docblocks that cite these numbers are not runtime strings and are unchanged. - `origin/main` was merged once (`e35c40a525`). It touches `cli/src/commands/start.ts` and adds a nightly e2e file, and shares no file with this PR. --- _Generated by [Claude Code](https://claude.ai/code/session_01VvcEokUG1tvVxkceYfR5XB)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
Prepares patch release 0.7.2 with updated system protocol artifacts.
Changes
Schema updates
New schemas cover:
Event,EventHandler,EventPersistence,EventBusConfig,EventQueueConfigTask,TaskRetryPolicy,WorkerConfig,WorkerStats,BatchTaskMetadataLoader,ServiceRegistry,PluginValidator,StartupOrchestratorAll packages bump to 0.7.2 via changeset. No breaking changes.
Original prompt
✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.