Skip to content

Patch release 0.7.2: System protocol schemas and documentation - #444

Merged
hotlong merged 4 commits into
mainfrom
copilot/create-patch
Jan 31, 2026
Merged

hotlong merged 4 commits into
mainfrom
copilot/create-patch

Conversation

Copilot AI commented Jan 31, 2026 •

Copy link
Copy Markdown
Contributor

Prepares patch release 0.7.2 with updated system protocol artifacts.

Changes

  • JSON Schemas: Generated schemas for system protocols (events, worker, metadata-loader, service-registry, plugin-lifecycle-events, startup-orchestrator)
  • Documentation: Added reference documentation for system layer protocols, organized by source files
  • Release artifacts: Changeset for 0.7.2, updated CHANGELOG

Schema updates

New schemas cover:

  • Event system: Event, EventHandler, EventPersistence, EventBusConfig, EventQueueConfig
  • Worker/Task: Task, TaskRetryPolicy, WorkerConfig, WorkerStats, BatchTask
  • Orchestration: MetadataLoader, ServiceRegistry, PluginValidator, StartupOrchestrator

All 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.

@vercel

vercel Bot commented Jan 31, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
spec Ready Ready Preview, Comment Jan 31, 2026 10:25am

Request Review

Copilot AI and others added 3 commits January 31, 2026 10:18
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>
Copilot AI changed the title [WIP] Add patch for code updates Patch release 0.7.2: System protocol schemas and documentation Jan 31, 2026
Copilot AI requested a review from hotlong January 31, 2026 10:21
@github-actions github-actions Bot added documentation Improvements or additions to documentation tooling labels Jan 31, 2026
@github-actions

Copy link
Copy Markdown
Contributor

This PR is very large. Consider breaking it into smaller PRs for easier review.

@hotlong
hotlong marked this pull request as ready for review January 31, 2026 10:41
Copilot AI review requested due to automatic review settings January 31, 2026 10:41
@hotlong
hotlong merged commit 360bec3 into main Jan 31, 2026
13 checks passed

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment on lines 8 to +16
<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';

Copilot AI Jan 31, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copilot uses AI. Check for mistakes.
Comment on lines +50 to +53
"durationMs": {
"type": "integer",
"description": "Execution duration in milliseconds"
},

Copilot AI Jan 31, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copilot uses AI. Check for mistakes.
Comment on lines +1 to +7
---
"@objectstack/spec": patch
"@objectstack/core": patch
"@objectstack/types": patch
"@objectstack/objectql": patch
"@objectstack/runtime": patch
"@objectstack/client": patch

Copilot AI Jan 31, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot uses AI. Check for mistakes.
<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" />

Copilot AI Jan 31, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
<Card href="./worker" title="Worker" description="Source: packages/spec/src/system/worker.zod.ts" />

Copilot uses AI. Check for mistakes.
Comment on lines +32 to +33
"translation",
"worker"

Copilot AI Jan 31, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"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.

Suggested change
"translation",
"worker"
"translation"

Copilot uses AI. Check for mistakes.
akarma-synetal pushed a commit to akarma-synetal/framework that referenced this pull request Oct 7, 2026
…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>

This branch was successfully deployed

1 active deployment
Preview — f77c0369 Deployed Jan 31, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size/xl tooling

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants