Implements docs/prds/artifact-sender.md (Approved). archie-core now sends generated artifacts to the offloaded.dev collaborative editor, whose POST /api/artifacts route, bearer service token, PocketBase-backed versions and idempotency semantics are the receiving contract. - [artifacts] config section: base_url + token SecretRef with a token_env fallback naming WORKSPACE_INGEST_TOKEN. An empty base_url disables the sender entirely; a base_url with an unresolvable token disables it with a warning, because a missing credential disables a capability rather than stopping the daemon. - internal/infrastructure/artifactsync: one-method Publish seam in the Courier posture, full source per publish (versions of record are snapshots), 503 retried three times with backoff, 401/400 surfaced immediately with the field reason, deterministic request ids (artifact:pr-review:<owner>/<repo>#<n>). - ReviewReport gains a pure markdown renderer in internal/domain/workflow: summary, one subsection per finding with the failure scenario and disposition when present, verified properties as a checked-clean list. - The daemon's PR reviewer publishes after a completed review when the sender is configured, records the editor deep link on the result, and degrades a failed publish to a log line -- publishing never fails the producing work.
3.8 KiB
Artifact sender
Status: Approved Revision: 1 Authority: this document
Purpose
archie-core publishes artifacts — design documents, review reports, research briefs, runnable pages — to the offloaded.dev collaborative editor. A person reads the artifact, comments on it, and the artifact page is the shared surface for iteration.
The receiving contract is owned by the editor: POST /api/artifacts with a bearer
service token, a closed field set, and server-side idempotency on requestId plus
last-write-wins on sentAt. This document owns only what archie-core sends.
Scope
Version one publishes one-way: archie-core sends, the editor receives. The first
producer is the pull-request adversarial review: a completed ReviewReport is
rendered to markdown and published after the review completes.
Chat-surface tools (create_artifact, update_artifact), comment read-back, share
tokens, and runnable-format producers (html, react, vue) are later slices. The
receiving contract already carries them; version one does not exercise them.
Configuration
- New
[artifacts]section:base_url(site origin),token(SecretRef) withtoken_envfallback namingWORKSPACE_INGEST_TOKEN. - An empty
base_urldisables the sender: no client is constructed, nothing is registered, and publishing degrades to a log line. - The token is runtime configuration. It is never baked at build time.
Sender
- New package
internal/infrastructure/artifactsyncexposing one method,Publish(ctx, Artifact) (string, error), where the string is the artifact URL. One-method injected seam, concrete client constructed by the boot path when the configuration resolves — thecrondelivery.Courierposture. - The client POSTs the frozen contract body. Each publish sends the complete source: versions of record are full snapshots, never diffs.
- A
503response is retried three times with backoff.401and400are not retried; they are logged with the field reason the response names. requestIdisartifact:<task-id>:<version>when the producer is task-backed, otherwiseartifact:<identity>:<sentAt-utc>. Sending the samerequestIdwith an equal or oldersentAtmust be a server-side no-op, which makes sender-side retry safe.
Report rendering
ReviewReportgains a pure markdown renderer ininternal/domain/workflow: the summary as the lede, one finding per subsection with file, line, verdict, level and the failure scenario, and the verified properties as a "checked clean" list. Findings carry their disposition when present.- The renderer performs no I/O and imports no infrastructure.
Attribution
actor: the producing identity. The reviewer publishes assystem:pr-reviewerwhen no task identity resolves; otherwise the task's identity name.source: the producing subsystem,pr-reviewfor version one.task: owner, repository and issue number from the task when one exists.
Failure behaviour
- Publishing never fails the producing work. A failed publish is logged with its status and reason; the artifact is republished on the next production of the same artifact.
- A successful publish records the artifact URL in the run report, so the PR description or task log links to the readable artifact.
- The published URL is the editor deep link for the artifact, keyed on its immutable id. archie-core never mints share links; sharing is an account-holder decision made in the editor.
Verification
- Client tests against a test server cover 201, 401, 400 with a field reason, and 503 retry behaviour.
- The report renderer test covers a report with findings, checks, dispositions and a not-run status.
- Configuration tests cover the disabled case, the
SecretRefpath and thetoken_envfallback.