feat(core,cli,sdk): close the SDK's remaining publication gates without publishing it (#295) by mbeacom · Pull Request #312 · mbeacom/adrkit

mbeacom · 2026-10-10T21:59:11Z

Closes #295, except for the publication act itself, which stays a later record's decision.

What and why

This closes everything ADR-0031 and ADR-0053 list before @adrkit/sdk can be published. Nothing is published. RELEASE_PACKAGES, exports, files, and the no-release assertions are untouched.

One "today" (ADR-0031 item 8, ADR-0053 item 3).
- Core exports todayUtcDate and replaces every inline copy: adr queue, the queue Action (bundle regenerated), adr new's scaffold, and the SDK's queue().
- The portal now takes the SDK's echoed default (queue().asOf) instead of computing its own.
- Tests ban the inline expression in all of them.
Core owns the CLI JSON (ADR-0031 item 4, ADR-0053 item 8).
- adr explain, adr lint, and adr new --json now come from packages/core/src/report, alongside the queue and graph formatters that already lived there.
- Byte-identical: old and new CLIs agree on all 106 outputs (stdout plus exit code) across 53 command lines over this corpus (with and without --as-of, including a ref) and the SDK fixtures. Committed goldens hold that.
Conformance fixture (ADR-0031 item 6, ADR-0053 item 5). It lives in packages/core/test/conformance/golden/: a fixed corpus, a manifest of commands and exit codes, and queue and check goldens. The CLI must reproduce them byte for byte, and the SDK must agree field by field.
Contracts documented (ADR-0031 item 5). docs/RELEASING.md gains "Consumer contracts: @adrkit/sdk and the CLI JSON", with the command → core shape → formatter table, the additive-only rule, and the ADR-0059 exception.

Checklist

DCO signed off.
Recorded decisions: ADR-0031 and ADR-0053. Ticked, after checking each against the tree: ADR-0031 items 4, 5, 6, 8; ADR-0053 items 3, 5, 8.
Schema changed: n/a.
@adrkit/core / packages/ci/src changed, so packages/ci/dist is regenerated under linux/amd64 Bun 1.4.2. I rebuilt twice and got identical bytes.
Every new test was observed failing first (ADR-0016). The plants are listed in each test-file header.
Full bun test: 4370 pass. typecheck, lint, check:deps, check:stale-refs, check:changelog, adr lint (59, clean), and emit:manifest pass.

Notes for reviewers

Gate label needed: this touches packages/ci/** and scripts/.
Still open for the publication record:
- ADR-0030 item 5 says adrkit publishes the fixture.
- ADR-0053 item 9: the portal exercises openDecisions and five of the six handle members in CI, but only as a build-time consumer. docs/sdk-surface.md now says exactly that.
- The SDK's QueueOptions.asOf doc still points callers at core's resolveAsOf. An SDK date helper would remove that.
Live markers in the fixture: retry.ts names 0002 and stale.ts names 0003. This repo's governing-decisions Action may post advisory context about them on this PR. That's harmless and has no exit-code effect.
Will conflict with fix(core,evaluator): qualified relatesTo/conflictsWith are inert in lint; cross-repo supersession is an error everywhere (#299) #307/fix(core): report repo-qualified affects matchers instead of skipping them silently (#300) #308 in packages/ci/dist and the CHANGELOG. Whichever merges later gets rebased with its dist rebuilt.

github-actions · 2026-10-10T22:02:55Z

Decisions governing this change

19 accepted decisions govern this change · 1 active proposal · 1 historical record

Show all 19 governing decisions and why each applies

0001 — Record architecture decisions as versioned markdown in git
- via path: docs/adr/**
0002 — Type the frontmatter as a MADR superset with an affects matcher
- declared by packages/core/test/conformance/golden/repo/src/sync/retry.ts:1 (@adr 0002)
0003 — Ship as a Spec Kit extension plus a standalone CLI, not a competing harness
- via path: packages/cli/**
- declared by packages/core/test/conformance/golden/repo/src/sync/stale.ts:1 (@adr 0003)
0016 — Require every check to be observed failing before it counts as coverage
- via path: packages/*/test/**
0022 — Scan inbound markers in check and CI without giving them exit-code authority
- via path: packages/ci/src/**
- via path: packages/cli/src/index.ts
0024 — Report the measured scan extent, not the window constant
- via path: packages/cli/src/index.ts
0029 — Scope Backstage publication as a downstream consumer, tiered on the entity-ownership mapping
- via path: packages/cli/src/index.ts
- via path: packages/cli/src/queue.ts
- via path: packages/core/src/index.ts
- via path: packages/core/src/queue/**
0030 — Keep extension surfaces that carry a dependency tree outside this repository
- via path: packages/ci/**
0031 — Publish a narrow consumer SDK as the contract, and document the CLI JSON as its sibling
- via path: docs/RELEASING.md
- via path: packages/cli/src/index.ts
- via path: packages/cli/src/queue.ts
- via path: packages/core/src/index.ts
- via path: packages/sdk/**
0032 — Publish one lockstep OCI image after the coordinated release succeeds
- via path: docs/RELEASING.md
0033 — Select interactive graph presentation at the CLI boundary while preserving piped DOT
- via path: packages/cli/src/index.ts
0035 — Execute the gates that certify a pull request from the default branch
- via path: packages/ci/**
0036 — Expose the governing-decisions Action through one root Marketplace entry point
- via path: docs/RELEASING.md
0039 — Derive a valid-time window from date and supersession, and resolve a git ref at the CLI boundary
- via path: packages/cli/src/index.ts
0041 — Regenerate committed artifacts on Dependabot pull requests with default-branch scripts behind a maintainer label
- via path: packages/ci/dist/**
0044 — Ratify a proposed record with adr accept and present the queue for terminals
- via path: packages/cli/src/queue.ts
0053 — Implement @adrkit/sdk over core's kernels and accept an in-repo consumer as its real consumer
- via path: docs/sdk-surface.md
- via path: packages/sdk/**
0054 — Publish a static decision portal for GitHub Pages, built outside the CLI from the SDK
- via path: packages/ci/portal/**
- via path: packages/portal/**
0059 — Aggregate decision corpora across an organization's repositories as a pinned, read-only federation
- via path: packages/ci/portal/**
- via path: packages/portal/**
- via path: packages/sdk/**

Active proposals touching this change (1)

These are not yet ratified and do not bind this change:

0051 — Record review state with adr approve, adr object, and adr resolve (proposed)
- via path: packages/cli/src/index.ts

Historical records that once covered this change (1)

These no longer bind this change, and are listed for context only:

0021 — Resolve inbound source annotations without changing the schema (superseded) — superseded by 0022
- via path: packages/cli/src/index.ts

_{Links point at b5109bf, this run's GITHUB_SHA. Run adr explain <path> locally to see why a file is governed.}

Copilot

🟡 Changes recommended

The portal still omits #295’s ISO-datetime support, while its new midnight test is flaky and SDK documentation is stale.

3 open findings

What changed in this PR

Closes most @adrkit/sdk publication gates without publishing the package.

Changes:

Centralizes UTC-date defaults and core-owned JSON formatters.
Adds CLI/SDK conformance fixtures and goldens.
Documents consumer contracts and updates ADR action items.

Marker-aware ADR compliance could not be independently verified because the adrkit MCP tools were unavailable.

File	Description
`CHANGELOG.md`	Records new contracts and fixture.
`docs/RELEASING.md`	Documents SDK and CLI JSON contracts.
`docs/sdk-surface.md`	Updates SDK status and consumer evidence.
`docs/adr/0031-….md`	Marks publication gates complete.
`docs/adr/0053-….md`	Updates SDK action items.
`packages/core/src/index.ts`	Exports date and report APIs.
`packages/core/src/queue/as-of.ts`	Adds `todayUtcDate`.
`packages/core/src/report/index.ts`	Adds canonical JSON reports.
`packages/core/src/scaffold/new.ts`	Uses shared UTC-date helper.
`packages/core/test/surface.test.ts`	Pins public exports.
`packages/core/test/report.test.ts`	Tests report contracts.
`packages/core/test/queue/as-of.test.ts`	Tests centralized date behavior.
`packages/core/test/conformance/golden/.gitattributes`	Enforces fixture LF endings.
`packages/core/test/conformance/golden/README.md`	Documents conformance usage.
`packages/core/test/conformance/golden/manifest.json`	Defines fixture commands.
`packages/core/test/conformance/golden/check.json`	Pins check output.
`packages/core/test/conformance/golden/queue.json`	Pins queue output.
`packages/core/test/conformance/golden/repo/docs/adr/0001-use-the-sync-protocol.md`	Adds fixture decision.
`packages/core/test/conformance/golden/repo/docs/adr/0002-retry-on-transient-failure.md`	Adds marker-only decision.
`packages/core/test/conformance/golden/repo/docs/adr/0003-poll-for-changes.md`	Adds superseded decision.
`packages/core/test/conformance/golden/repo/docs/adr/0004-push-changes-over-websockets.md`	Adds successor decision.
`packages/core/test/conformance/golden/repo/docs/adr/0005-batch-sync-writes.md`	Adds reviewed proposal.
`packages/core/test/conformance/golden/repo/docs/adr/0006-adopt-a-queue.md`	Adds unqueued proposal.
`packages/core/test/conformance/golden/repo/docs/adr/0007-sketch-offline-mode.md`	Adds draft decision.
`packages/core/test/conformance/golden/repo/docs/adr/notes/0008-nested-record.md`	Exercises skipped discovery.
`packages/core/test/conformance/golden/repo/src/cache/lru.ts`	Adds ungoverned fixture path.
`packages/core/test/conformance/golden/repo/src/sync/protocol.ts`	Adds pattern-governed path.
`packages/core/test/conformance/golden/repo/src/sync/retry.ts`	Adds live marker path.
`packages/core/test/conformance/golden/repo/src/sync/stale.ts`	Adds stale marker path.
`packages/cli/src/index.ts`	Uses core JSON report builders.
`packages/cli/src/queue.ts`	Uses shared UTC-date helper.
`packages/cli/test/conformance.test.ts`	Verifies fixture outputs.
`packages/cli/test/json-report.test.ts`	Pins JSON compatibility.
`packages/cli/test/fixtures/json-report/.gitattributes`	Enforces golden LF endings.
`packages/cli/test/fixtures/json-report/new.json`	Pins new output.
`packages/cli/test/fixtures/json-report/lint.json`	Pins lint output.
`packages/cli/test/fixtures/json-report/lint-broken.json`	Pins failed lint output.
`packages/cli/test/fixtures/json-report/explain-retry.json`	Pins marker explanation.
`packages/cli/test/fixtures/json-report/explain-protocol.json`	Pins pattern explanation.
`packages/cli/test/fixtures/json-report/explain-stale.json`	Pins stale-marker explanation.
`packages/cli/test/fixtures/json-report/explain-lru.json`	Pins ungoverned explanation.
`packages/cli/test/fixtures/json-report/explain-missing.json`	Pins absent-path explanation.
`packages/cli/test/fixtures/json-report/explain-broken.json`	Pins corpus-error explanation.
`packages/cli/test/fixtures/json-report/explain-broken-as-of.json`	Pins temporal corpus-error output.
`packages/cli/test/fixtures/json-report/explain-as-of-retry.json`	Pins temporal marker output.
`packages/cli/test/fixtures/json-report/explain-as-of-protocol.json`	Pins temporal pattern output.
`packages/cli/test/fixtures/json-report/explain-as-of-stale.json`	Pins temporal stale output.
`packages/cli/test/fixtures/json-report/explain-as-of-lru.json`	Pins temporal ungoverned output.
`packages/cli/test/fixtures/json-report/explain-as-of-missing.json`	Pins temporal absent output.
`packages/sdk/src/index.ts`	Clarifies queue default contract.
`packages/sdk/src/decision-set.ts`	Uses core UTC-date helper.
`packages/sdk/test/conformance.test.ts`	Compares SDK with CLI goldens.
`packages/portal/src/generate.ts`	Sources default date from SDK.
`packages/portal/test/generate.test.ts`	Tests SDK-derived default.
`packages/ci/src/queue-action-entrypoint.ts`	Uses shared UTC-date helper.
`packages/ci/dist/queue-action.js`	Regenerates queue bundle.
`packages/ci/dist/portal-action.js`	Regenerates portal bundle.

🧠 Review effort: Balanced

…ut publishing it (#295) - ADR-0031 item 8 / ADR-0053 item 3: core exports todayUtcDate, the absent-input `--as-of` default, and replaces every inline copy: adr queue, the queue Action (bundle regenerated), adr new's scaffold, and the SDK's queue(). The portal now takes the SDK's echoed default (queue().asOf) instead of computing its own. Tests ban the inline expression in all of them. - ADR-0031 item 4 / ADR-0053 item 8: `adr explain`, `adr lint`, and `adr new --json` now come from core formatters (packages/core/src/ report). Old and new CLIs produced byte-identical stdout and exit codes on 53 command lines over this corpus and the SDK fixtures; committed goldens hold it. - ADR-0031 item 6 / ADR-0053 item 5: a conformance fixture under packages/core/test/conformance/golden: the CLI must reproduce its queue and check goldens byte for byte, and the SDK must agree with them. - ADR-0031 item 5: docs/RELEASING.md documents the SDK and CLI JSON consumer contracts. Nothing is published: RELEASE_PACKAGES, exports, files, and the no-release assertions are untouched. packages/ci/dist rebuilt under linux/amd64 Bun 1.4.2. Every new test was observed failing first (ADR-0016). Ticked: ADR-0031 items 4, 5, 6, 8 and ADR-0053 items 3, 5, 8. Signed-off-by: Mark Beacom <m@beacom.dev>

…portal takes ISO datetimes Review on #312 found three gaps: - #295 promised the portal would accept ISO datetimes once the default moved to core, but it still refused them. The SDK's queue({ asOf }) now resolves a supplied value through core's resolveAsOf, the grammar `adr queue --as-of` uses (a bare date, or an ISO datetime with an explicit zone), and echoes the resolved UTC date in QueueView.asOf; anything else throws RangeError. The portal passes the caller's asOf to queue() and builds from view.asOf, so it accepts datetimes while importing only the SDK. No new SDK symbol; the doc no longer tells callers to reach into core. - The portal's default-date test could fail across UTC midnight; it now brackets both readings and compares only when no midnight passed. - docs/sdk-surface.md and the ADR-0031 item 8 note still described the portal's removed copy and bare-date rule. New tests were observed failing first (ADR-0016), including SDK/CLI equivalence for a datetime asOf on all four corpora. Signed-off-by: Mark Beacom <m@beacom.dev>

…est the portal bundle's datetime as-of packages/ci/dist rebuilt under linux/amd64 Bun 1.4.2 on top of main (after #307, #308, #314). The portal bundle now takes the SDK's --as-of grammar: a new bundle test resolves 2026-01-08T23:30:00-05:00 to 2026-01-09, and the usage-error test uses a timezone-less datetime with core's message. Both failed against main's bundle (ADR-0016). Signed-off-by: Mark Beacom <m@beacom.dev>

Copilot AI balanced review requested due to automatic review settings October 10, 2026 21:59

Copilot started reviewing on behalf of mbeacom October 10, 2026 21:59

View session

Copilot AI reviewed Oct 10, 2026

View reviewed changes

Comment thread packages/portal/src/generate.ts Outdated

Comment thread packages/portal/test/generate.test.ts Outdated

Comment thread docs/sdk-surface.md Outdated

mbeacom self-assigned this Oct 10, 2026

mbeacom added enhancement New feature or request gate-change-acknowledged A maintainer has seen and accepted this PR's change to the CI gate surface (ADR-0035) labels Oct 10, 2026

mbeacom added 3 commits October 10, 2026 19:34

mbeacom force-pushed the feat/sdk-publication-gates branch from e9f3a63 to 3eab946 Compare October 10, 2026 23:40

github-actions Bot removed the gate-change-acknowledged A maintainer has seen and accepted this PR's change to the CI gate surface (ADR-0035) label Oct 10, 2026

mbeacom added the gate-change-acknowledged A maintainer has seen and accepted this PR's change to the CI gate surface (ADR-0035) label Oct 10, 2026

mbeacom merged commit e491a78 into main Oct 10, 2026
23 of 24 checks passed

mbeacom deleted the feat/sdk-publication-gates branch October 10, 2026 23:54

Navigation Menu

Repository navigation

feat(core,cli,sdk): close the SDK's remaining publication gates without publishing it (#295) - #312

feat(core,cli,sdk): close the SDK's remaining publication gates without publishing it (#295)#312
mbeacom merged 3 commits into
mainfrom
feat/sdk-publication-gates

mbeacom commented Oct 10, 2026

Uh oh!

github-actions Bot commented Oct 10, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

mbeacom commented Oct 10, 2026

What and why

Checklist

Notes for reviewers

Uh oh!

github-actions Bot commented Oct 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Decisions governing this change

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions Bot commented Oct 10, 2026 •

edited

Loading