Skip to content

feat(moduleauthority): ReadJournal reads the host's journal by page - #40

Draft
crisfiorini-oss wants to merge 18 commits into
codefly-dev:mainfrom
crisfiorini-oss:feat/read-journal
Draft

feat(moduleauthority): ReadJournal reads the host's journal by page#40
crisfiorini-oss wants to merge 18 commits into
codefly-dev:mainfrom
crisfiorini-oss:feat/read-journal

Conversation

@crisfiorini-oss

@crisfiorini-oss crisfiorini-oss commented Oct 13, 2026 •
edited
Loading

Copy link
Copy Markdown

Add bounded journal reads to the existing moduleauthority.Client, preserving its authenticated transport, module-credential cache and refresh-once behavior. Journal positions remain opaque and the host marks delivery machinery.

Draft: hosted CI requires repository-admin approval. Publication also requires the actual host release and compatible shared owner releases; no release version is guessed.

Changes

  • Extend Client.ReadJournal; reuse the existing client, broker, credentials, HTTP/2 transport, Connect errors and decoder. Remove the extra reader factory and its duplicate fixtures. No new credential producer, cache, retry loop or transport is added.
  • Validate requests with the existing protobuf validator and the explicit 500-entry page bound. Reject nil entries and invalid protobuf timestamps before decoding. Preserve the facade's existing handling of absent timestamps.
  • Regenerate the complete host-owned schema, retaining current datasource/object-storage, installation, workload admission and task-binding contracts. Shared Core and Authority descriptors remain canonical imports rather than copied schemas.
  • Document the generated interface additions and module package 0.2.0. Keep generated directories collapsed and authored facades, configuration, locks and source provenance visible.
  • Record the actual development dependency floor: Authority client v0.0.0-20261026143932-67b85b14a942 requires Core v0.19.7-0.20261026092055-b23dc13543b2; Go 1.27.3 remains required. These refs are not represented as released tags.

Classification: fix, at the existing journal/schema client owner.

Build or reuse Searched and verified Result
Journal client Existing module-authority client, broker, credential refresh, HTTP/2 tests and host ReadJournal Extend Client.ReadJournal and remove the additional reader factory. Request validation and page decoding stay in this owner; consumers map the existing projection.
CI execution Existing owner workflow and fork Actions permissions Run the same complete gates on branch pushes/manual dispatch. No second pipeline, omitted lane or weaker token permission.
Schema generation Complete host schema and this SDK's pinned Buf/plugin template Generate only saas/. Shared Core and Authority descriptors are import-only.
Installation approval Host import and canonical Authority client implementation; older host-pinned client lacks ConsentApproval Use the canonical implementation and its declared Core floor; no copied schema or dependency override.
Gateway conformance Existing protected host listener, presenter fixtures and conformance script Preserve real listener and refusal assertions rather than add consumer-side fake issuer qualification.

Validation

Rebased onto upstream main 29ab843f; pushed head f73008be0b8703dc62f9f70e600b44419dd9e411. SOURCE.txt records exact host protocol revision bb66a84cfff053bcccf3f0842bc6ffa6b2e0d159. Later host commits change Go/tests/audit metadata, not these schema/generator inputs. Publication must regenerate from the actual host tag.

  • Final scoped ReadJournal tests PASS (0.179s); scoped journal race tests PASS (1.511s); public API boundary PASS (3.974s). Tests cover real HTTP/2 reads, refresh behavior, request bounds and malformed timestamps. Whitespace and formatting checks pass.
  • Pinned Buf 1.73.0 generation and independent complete regeneration were byte-identical. Complete generated outputs remain committed, including main's object-storage source fields.
  • All ten canonical real host-gateway conformance cases PASS with race detection against the exact clean recorded source (1.661s), without skips. The final cleanup does not change gateway credential minting.
  • Extend this existing CI workflow to source-branch pushes and manual dispatch, retaining all original jobs, assertions and read-only permissions. Full fork-hosted CI PASSes all three jobs on exact f73008b: test/build/vet/race, complete generation drift and real host-gateway conformance. This workflow-only commit leaves every Go source, module/checksum, source-provenance and generation input identical to Runtime's checksum-pinned 4bbea05 SDK revision. The upstream PR workflow still requires repository-admin approval; no upstream workflow was approved. Fork qualification does not bypass that merge gate. Full local suites were not repeated.

Release prerequisites

Release the host, regenerate from the actual host tag and adopt compatible shared owner releases before SDK publication. Downstream consumers require the resulting actual SDK release and green CI.

This PR does not claim a composed Runtime credential producer: the shared Authority cannot mint the unbound module-capabilities identity assumed by the earlier consumer adapter. Runtime now refuses enabled journal startup until its producer route is composed and reviewed. No live audit-delivery or warehouse round trip is claimed.

@crisfiorini-oss crisfiorini-oss mentioned this pull request Oct 13, 2026
Open
@crisfiorini-oss
crisfiorini-oss marked this pull request as ready for review October 13, 2026 15:18
crisfiorini-oss and others added 10 commits October 21, 2026 20:05
@crisfiorini-oss @claude
chore(gen): ReadJournal contract, waiting for the saas-starter release
bc90fdb 
STOPGAP, labelled: ModuleCapabilitiesService.ReadJournal and its messages
(ModuleReadJournalRequest, ModuleJournalEntry, ModuleReadJournalResponse) are
not in module-saas-starter v0.0.94 and no release carries them yet. These two
files were generated by this repo's buf.gen.yaml (buf 1.73.0, pinned plugins)
from the v0.0.94 proto with the agreed wire contract added to
module_capabilities.proto in a scratch checkout. The v0.0.94 proto alone
reproduces gen/ byte for byte, so the diff is the contract and nothing else.

The gen-drift job fails until gen/ is regenerated from the release that
publishes the contract; SOURCE.txt says so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@crisfiorini-oss @claude
feat(moduleauthority): ReadJournal reads the host's journal forward
c91ffdd 
Client.ReadJournal(ctx, afterSeq, limit, types) calls
ModuleCapabilitiesService.ReadJournal on the authority endpoint as the module,
through callAsModule like the sibling methods: host codes preserved, a rejected
capability refreshed once, nothing else retried. JournalPage.NextAfterSeq is
the host's resume point. A negative position, a limit outside 0..500 or no
type is ErrInvalidJournalRead before any call.

Depends on the generated contract in the previous commit, which is waiting for
the saas-starter release (see CHANGELOG.md).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@crisfiorini-oss @claude
feat(moduleauthority): ReadJournal reads by page with opaque positions
2f99945 
ReadJournal(ctx, after, limit, types, deliveryBindings) takes and returns opaque
positions: a reader stores and compares them, never parses them. JournalEntry
gains Position and DeliveryMachinery (the host's mark for a mint or exchange of
one of the named delivery bindings, or the caller's own module mint), and
JournalPage.NextAfter replaces NextAfterSeq. An empty type or delivery binding id
is ErrInvalidJournalRead before any call. The host fake serves the new contract
and the tests follow it.

STOPGAP, labelled, as before: the regenerated gen/ carries the contract
(ModuleReadJournalRequest with after and delivery_bindings, ModuleJournalEntry
with position and delivery_machinery, ModuleReadJournalResponse with next_after)
from a scratch saas-starter v0.0.94 checkout plus the contract, by this repo's
buf.gen.yaml (buf 1.73.0). It replaces the earlier contract, which was never
published. The gen-drift job fails until gen/ is regenerated from the
saas-starter release that publishes it; SOURCE.txt and CHANGELOG.md say so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@crisfiorini-oss @claude
feat(moduleauthority): export JournalStart, the position before the o…
381afff 
…ldest entry

The host defines the literal "start": it accepts it as ReadJournal's after and as
the from of its delivery operation, and never returns it as an entry's position.
A reader with no position of its own starts a range from it. The host fake
accepts it and a test reads from it. The regenerated proto comment says so
(comment-only change in gen/, still waiting for the saas-starter release).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@crisfiorini-oss
fix(sdk): reproduce journal API from the exact host contract
fd1472d
@crisfiorini-oss
test(moduleauthority): use sealed journal credential fixtures
413ed1f
@crisfiorini-oss
fix(sdk): reconcile journal schema and workload gateway conformance
c11c47f
@crisfiorini-oss
chore: mark generated SDK bindings for review
bdb8717
@crisfiorini-oss
fix(sdk): regenerate journal API against current host authority
10b87f2 
Generate the complete host-owned schema from module-saas-starter d5ea5dc75790dfeb55a5492eaa7c7b759df7a84d with the pinned SDK plugins. Consume the exact host Core contract and remove ApprovedBuild from WorkContextSources, matching the current live verifier API. Keep Work Contexts opaque and retain the real workload-listener conformance assertions.
@crisfiorini-oss
docs(sdk): align journal provenance with rebased host source
4a785ff 
Record the exact final host source after its rebase onto current main. Preserve current SDK facade and mint APIs, keep journal changes under Unreleased, and document the protected workload-listener conformance coverage. The full owner generation reproduces from the unchanged accounts proto tree.
@crisfiorini-oss
crisfiorini-oss marked this pull request as draft October 26, 2026 19:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@crisfiorini-oss