Compare commits

...
49 Commits
Author SHA1 Message Date
sam 19cf9ae2ab chore(release): v1.40.0
deploy / gate (push) Failing after 5m33s
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped
2026-09-23 13:30:57 +10:00
sam 67c2dff3e1 merge(release): bring the v1.39.0 release commit into sams-cleanup
The branch and main diverged at 8faa0f6a: the release commit was cut on
main while the branch kept advancing with the park-classification wave.
Merging main here first, so main can fast-forward to the branch tip
without a merge on the release side. No content conflicts: the release
commit touches the changelog and news artifacts only.
2026-09-23 13:23:16 +10:00
sam 10dd85443d feat(staterpc,daemon): park classification on the wire and at the park sites
Domain fields ParkClass/RemediationRounds landed in d6f61c2c; this is
the wire and daemon half. Task gains park_class (32) and
remediation_rounds (33) and maps both directions; the classified park
write crosses the wire as ParkTask on a narrow TaskParker contract
(TaskLifecycle stays under the 8-method cap), with conformance
coverage local + grpc including the stale-guard sentinel and
needs_human normalization. Every daemon park site now states its
class: terminal for a repo that left config and a retired identity,
transient for the environmental parks (worktree, storage, grants,
taskrun), and identityMayAct returns the class beside its reason.
2026-09-23 13:18:08 +10:00
sam 53bdbd3309 fix(staterpc): carry park class and remediation rounds across the wire
d6f61c2c added Task.ParkClass and Task.RemediationRounds to the domain
without the wire half; the parity guard went red. Add the two proto
fields (32/33) and map both directions in values.go.
2026-09-23 13:10:31 +10:00
sam 5d6fbd5c30 fix(release): CI owns the release stamp; :latest moves only from a release
Two beads, one root: four sites stamped a version and only two of them were CI.

`Taskfile.yml`'s build and `install.sh` derived GATEWAY_VERSION/RUNTIME_VERSION
from `git describe`, so a from-source build claimed a release it was not
running, and the stamp became a function of the commit graph -- the one input a
content-checksum build cache cannot see. An empty commit moved `git describe`
while `task build` reported "up to date" and shipped the previous stamp
(archie-core-pdq2). Both sites now stamp `dev`: a source build says so, and the
version a release carries is written into the artifact CI publishes. That
removes the non-file input rather than caching it, and traceability for a local
build is the checkout it came from.

`deploy.yml` published `:latest` from any push to main, so a release's own
stamping survived only until the next ordinary commit -- minutes, in an active
repo -- and a host deploying :latest reported dev, leaving the update path
unable to tell current from stale (archie-core-i5nb). `:latest` now moves only
from a commit that IS a release; every other build publishes `:edge` (mutable,
newest main) and `sha-<commit>` (immutable). A host that runs releases follows
`:latest`; a host that tracks main follows `:edge`, which RELEASING.md now says.

Verified: `task build` reports `archied dev`; the new workflow test fails
against the old workflow on all five guards and passes after; deploy.yml
parses; install.sh passes `bash -n`.

Gated with `task check` (exit 0) at 8faa0f6a -- the v1.39.0 base, CI-green --
with these five files applied. It is NOT gated at HEAD: HEAD carries an
unrelated red, `TestTaskProtoCarriesEveryDomainField`, because d6f61c2c added
ParkClass and RemediationRounds without the proto mapping. This change neither
causes nor fixes that.
2026-09-23 13:09:01 +10:00
sam 3940487335 feat(webui): show the park class beside the Parked badge
The classification rides the API for free (taskView embeds task.Task),
so this is the read side only: a parked row shows what kind of
intervention it needs -- needs you, transient, terminal -- as a chip
with the answer in its tooltip, instead of a bare Parked every time.
Non-parked rows render nothing.
2026-09-23 12:57:27 +10:00
sam d6f61c2c6f feat(workflow): typed park classification and split remediation budgets
The F2+F3 schema wave from the auto-fix/resume investigation, sequenced
together as one migration. Every failure funneled to one parked status
with free-text ParkReason, and Task.RetryCount doubled as the
operator-retry budget and the review-remediation round budget -- so N
operator retries ate the remediation budget, a repo-level round cap
could re-park a task an operator had just legally retried, and no
surface could answer what a park needed from an operator.

Park class (F2): a producer-recorded vocabulary in taskstate --
needs_human (the default, so an unclassified park always reads as
operator-actionable), transient (environmental; a requeue can succeed),
terminal (retrying is pointless). Recorded at the park site, never
inferred from reason text; NormalizeParkClass makes unknown values
persist as needs_human. Transition-to-parked defaults the class, so
every existing unclassified park site reads correctly with no call-site
churn; the classified ParkTask write follows for parks that know
better. Requeue, RetryTask and BeginRemediation clear the class back to
the default with the reason.

Split budgets (F3): Task.RemediationRounds is the remediation's own
budget; RetryCount stays the operator's. The round-cap stage counts and
caps rounds; operator retry keeps counting RetryCount and can drive a
task to dead without touching rounds. remediation_rounds is a
presence-gated migrator column written through Update.

Known state: proto fields, the ParkTask RPC, the staterpc mapping and
the daemon-side park-site classification follow in the wire half of
this wave (the proto parity test is intentionally red until then).
2026-09-23 12:55:03 +10:00
sam ee78bfa7bc chore(release): v1.39.0
deploy / gate (push) Failing after 5m48s
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped
2026-09-23 12:53:48 +10:00
sam 8faa0f6a30 feat(daemon,forge): the review-reaction producers
Sequencing steps 6 and 7 of pr-review-remediation.md: the consumer
landed in 052e350b, and these are the two sources that feed it.

Webhook (decision 2, low latency): the GitHub receiver decodes
pull_request_review and pull_request_review_comment events behind the
existing HMAC verification and publishes the same typed reaction the
poller produces, keyed source-independently so PublishUnique collapses
the two sources. Only submitted/created carry a verdict to remediate;
edited and dismissed are acknowledged. Reaction deliveries are
rate-limited per source (decision 6's 'add when the receiver gains a
second event family'), and the reaction path carries no dispatch
predicate -- eligibility is the consumer's owned-PR lookup.

Poll (both forges, the no-webhook backstop): one shared scan over all
pr_open tasks, each with the forge client its own identity owns
(reconcilePRs's shape), listing reviews and comments since per-task
persisted high-water marks and skipping the owning identity's bot user
(decision 5's own-comment exclusion, which the poll is positioned to
make identity-correct).

The cursors are two, not one: review IDs and comment IDs are independent
forge sequences, and a combined high-water mark would silently skip
reviews once a larger comment ID landed. watch_comment_id -- dead since
the comment-watch design it was created for never shipped -- carries the
comment cursor; review_cursor is a new presence-gated migrator column,
and SetReviewCursors is its guarded RPC (pr_open only, so cursors never
move under a run that owns the task). forge.ReviewComment gains ReviewID
so a comment is collectable into its review's unit (decision 5) on both
forges, and forge.Review gains Body so poll-delivered reviews carry
their summary.

Note: the store/proto/facade half of this work landed early in a65eae24
under a release session's message -- a shared-checkout collision, kept
rather than rewritten; that commit carries the review_cursor migration
and the SetReviewCursors contract, this one carries the producers.
2026-09-23 12:41:53 +10:00
sam 59614cc63f style(update): adopt the formatter's alignment in the watchdog test
task check's fmt pass rewrites this literal; the version committed with
the readiness-wait change predated that pass.
2026-09-23 12:30:10 +10:00
sam 40f2e13f0b fix(docs): derive the docsite artifact from the commit, not the working tree
docs:artifact:check regenerated the artifact from a directory walk of
docs/, which also sees an UNTRACKED page. The committed artifact then
looked stale and the gate demanded a regeneration that was already
correct -- one that would have committed a page belonging to no commit.
It cost two sessions in one day: a migration branch, and an unrelated
writer adding a PRD.

Enumerate through `git ls-files --cached` instead, so a page the commit
carries is required in the artifact and a working-tree scratch file is
not. The index counts as well as HEAD, deliberately: a page staged for
this commit is about to be carried by it. Outside a git work tree there
is no commit to disagree with, so the walk is kept and says so on stderr
rather than passing as the stronger guarantee.

Test fails against the walk with the gate's own message ("is stale;
regenerate it by running ...") and passes against the enumeration.
2026-09-23 12:29:29 +10:00
sam a65eae2458 docs(agents): a bead never carries production instance detail
Beads sync to a Dolt remote, so anything written into one is published.
Two beads filed earlier today named an operator host, its internal
address and its filesystem paths -- the tracker was treated as a private
store, which it is not.

The rule is stated where the tracker is described, next to the existing
one about .beads/ never reaching a commit, because it is the same class:
the tracker is not a private store. Host-specific facts belong in the
operator's memos instance, which a bead may point at.
2026-09-23 12:29:29 +10:00
sam 052e350bf1 feat(daemon): wire the review-reaction consumer to remediate runs
The remediate workflow was registered but had no trigger: the reaction
stream was provisioned, the envelope, resolver and owned-PR lookup all
landed, yet nothing consumed the stream (pr-review-remediation.md's
sequencing left the consumer for this step). The daemon now drains the
reaction stream each cycle, before the task drain, so a reaction can be
claimed in the same pass that carried it.

Per decision 3, the store's owned-PR lookup is the authorization
boundary: an unmatched, merged or closed PR drops with a counter, and a
public reaction can never start an agent against a foreign repository.
Per decision 5, a review is the unit of remediation -- its comment
events are appended to the unit while it is queued and dropped once the
run is claimed (the round cap bounds the exchange); a standalone comment
is its own unit of one; approved reviews never remediate; and archie's
own comments, matched on the owning identity's bot user, are excluded so
its replies cannot retrigger it.

The guarded BeginRemediation/UpdateReviewPayload store methods are the
dedup: the pr_open -> queued transition carries the review unit in the
same write, so re-delivered reactions fail the status guard instead of
starting a second round. Both are new StateStoreService RPCs following
the Requeue shape, covered by the local/grpc conformance battery.
2026-09-23 12:08:44 +10:00
sam 2393ec6dae docs(prds): approve the master-detail run page PRD
The maintainer approved task-run-master-detail.md after the
adversarial-review round; its status moves Draft -> Approved while the
work it describes is completed and verified.
2026-09-23 11:36:16 +10:00
sam 00cfd6bda0 fix(webui): reset the stage filter on an attempt switch
A stage filter is a command scoped to the attempt it was made on: the
rail set it against that attempt's stage list. selectAttempt and
performRetry left filters untouched, so a stage selected on attempt 2
carried into attempt 1 -- a same-named stage there rendered as selected
without ever being commanded, or the log stayed narrowed to a stage the
new attempt does not have. The stage filter now resets when the selected
attempt changes; the level filter is attempt-agnostic and survives.

The master-detail PRD absorbs the adversarial review's verified findings:
the reload claim is narrowed to the URL contract (filters are not in the
URL), the unimplemented scroll and pinned claims are dropped, the
unnamed-stage and level-filter contracts are stated, the rail inventory
is corrected, and the acceptance list gains criteria for the
command-not-binding rule, attempt-switch reset, and keyboard selection.
2026-09-23 11:31:58 +10:00
sam 89fc8fc7f1 fix(webui): group live activity by payload, not by event kind
The first cut grouped consecutive same-kind events, but the real noise
shape is an interleave: one background cycle emits curator_run,
session-memory and curator_action events carrying the same payload, and
kind-keyed grouping left them all visible. The grouping key is now the
rendered detail plus the task, so one cycle of noise collapses to one
row regardless of which internal kind emitted each event, while events
carrying different information never merge. Verified against a live
daemon: 50 background events collapse to one expandable row.
2026-09-23 11:20:45 +10:00
sam fd3f661a73 feat(webui): split the task run page into a master-detail pane
The five tabs gave the stage rail less than a third of the screen and
disconnected the log stream from the stage that produced it. The stage
rail is now the page's master pane, always visible; the four context
panels are the inspector and own the tab bar. Selecting a stage commands
the inspector to the log tab with that stage's filter set; clicking the
selected stage clears it. Selection is a command, not a binding -- the
operator can change the filter afterwards.

No endpoint, RPC or contract changed. tab=stages still resolves, to the
log tab; every inspector tab and attempt deep-link survives a reload.
Below the shell's 900px frame breakpoint the rail stacks above the
inspector. Design of record: docs/prds/task-run-master-detail.md (Draft,
per-run panel contracts unchanged from task-run-detail.md).
2026-09-23 11:20:45 +10:00
sam cdedbaa1f5 feat(webui): collapse runs of background telemetry in live activity
The feed's 50 raw events were dominated by consecutive same-shape
background rows (session-memory cycles, runner calls), which buried the
milestones the dashboard exists to surface. Consecutive events sharing
one label and one task now collapse into a group row with an xN badge;
expanding it reveals its events in place. The grouping is consecutive,
not global, so interleaved kinds keep their order and a milestone is
never merged with an event that merely shares its kind.

The projection is a pure view over the store's raw stream (activity-group.ts,
table-tested); the store keeps every event. Group rows keep ActivityRow's
link contract, and the disclosure button is stop-propagated inside the
first cell so it never fights the row-level link.
2026-09-23 11:07:14 +10:00
sam f0c1b34882 docs(skills): add archie-web-ui guidance for dashboard work
Carries the stack facts agents must not fight (token file, ui/dist as a
generated LAW asset, feature layout, UI gates), the operational-tool
design rules, the WCAG AA bar, and the rule that external design
prototypes are specs to translate, never code to port.
2026-09-23 11:05:58 +10:00
sam fde21c43d4 fix(webui): clear WCAG AA on info and subtle text tokens
The info token doubled as badge text on info-soft and as the log-level
label, and failed 4.5:1 there (4.29:1 dark over card, 4.45:1 over glass;
light theme 4.11:1 on canvas, 3.58:1 on its soft). Dark --info moves to
#B08BF8, light --info to #6F47A6, both clearing 4.5:1 on every surface
they land on. Light --fg-subtle moves to #675E6F for the wash-composited
canvas where the old value measured 4.44:1. Measured pairs recorded at
the token definitions.
2026-09-23 11:05:56 +10:00
sam ec38ad604d test(release): the runtime image is published for a tagged release, not only an archie/v* tag
deploy / gate (push) Failing after 3m44s
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped
TestDeployWorkflowOnlyPublishesRuntimeImageForRuntimeTag pinned the
per-component contract: the agent image builds only when an archie/v* tag is
at HEAD. One-stream releases create only a v* tag -- release.sh has no
archie/v* arm any more -- so that selector can never fire again, and the
agent image would never be rebuilt. `docker compose pull agent` would fetch
an ancient image forever.

The test's own subject is still right and is kept: the gateway build stays
unconditional and the runtime build stays guarded. The guard now names both
selectors, and the comment says why the legacy arm remains (history is not
re-tagged). Caught by CI, not by me: I changed the workflow and pushed
without re-running the gate on that tree.
2026-09-23 04:01:16 +10:00
sam 3fdffa7203 fix(release): teach the image job the one-stream tag
The one-stream change updated the changelog gate, release.sh and the docs,
but missed the image job. Measured on the v1.37.1 run: `gate` resolved
1.37.1 from the `v*` tag and then warned "No release tags at HEAD", while
`build-and-push` read only `archied/v*`/`archie/v*`, found neither, and fell
back to `dev+<sha>` for both components. It also skipped the archie-agent
image entirely, because that step was gated on an `archie/v*` tag being
present -- so a one-stream release would have published a dev-stamped
gateway and never rebuilt the runtime.

Three changes:
- version resolution falls back to the one-stream `v*` tag, so both
  components are stamped with the release version;
- the runtime image builds on a `v*` release as well, since one version
  covers the release; a legacy gateway-only release still skips it, which
  is what release_tag exists to distinguish;
- the "no release tags at HEAD" warning recognises `v*`, so a real release
  stops being told it is not one.
2026-09-23 03:51:36 +10:00
sam ee56852064 fix(build): ship the one-stream changelog in the archied image
Dockerfile.archied still copied CHANGELOG.archied.md and CHANGELOG.archie.md,
which the one-stream release deleted. The image build therefore failed at
the COPY stage, so no images and no GitHub Release have been published
since the stream merged -- v1.37.1 failed the same way, and this release
failed with it.

Copy the single CHANGELOG.md the streams merged into. Verified by building
the image: the build completes and /usr/share/archie/CHANGELOG.md is
present and readable in the result.
2026-09-23 03:50:41 +10:00
sam 91691fde93 chore(release): v1.38.0 2026-09-23 03:36:31 +10:00
sam 4fe53f1028 merge(sams-cleanup): the PocketBase event-capture migration and its follow-ups
Moves event capture, mappings and bindings onto PocketBase-owned collections
in internal/infrastructure/edastore, and adds the read-only stateadmin
surface over the task database. Follow-ups included:

- the event feed cursor becomes a total order over a fixed-width timestamp
  with an opaque string cursor, so it no longer depends on rowid
  monotonicity;
- cron schedules get next-run arithmetic, so a cron job fires instead of
  returning ErrScheduleUnsupported;
- binding and mapping edits announce on the activity stream, so a dashboard
  edit is visible without a manual refresh;
- an unresolvable task identity fails closed rather than falling back to the
  root forge's credential;
- tool_call events project into the tool_calls collection, which had a
  schema and no writer.

Also: the branch is brought back to a passing task check, which it had not
been for the whole migration -- two pre-existing failures, an unrecorded
int64-to-string proto break and a stale generated docs artifact.
2026-09-23 03:33:49 +10:00
sam 1012384b5e chore(fmt): adopt go fix's range-over-int in two loops
task check's fmt pass rewrites both, so the committed tree was not
fmt-canonical. Adopted verbatim, per the repository's rule that formatting
changes from the configured formatter are law.
2026-09-23 03:33:32 +10:00
sam 46033dc5b3 merge(run/pb-toolcalls): project tool_call events into the tool_calls collection
Lane D. The collection existed in the event-capture schema with nothing
writing it; tool calls reached only the on-disk task log, readable as text
and never queryable.

The projection is a decorator on the State Store's task store, wired in
stateStoreDeps. InsertEvent persists the event first and only then, for a
tool_call event, writes one row. A projection failure is counted and logged
but never returned: event persistence is load-bearing, the transcript is
observability, and failing a task write because its shadow failed trades
the fact for the record of it. With no event-capture store the task store
passes through unwrapped.

The event adapts to the existing collection rather than the collection to
the event; args and duration_ms stay reserved. InsertToolCall stays silent
on the notify hook, matching the dispatch tables rather than the
operator-editable ones -- tool calls are high-frequency telemetry, not
dashboard activity.
2026-09-23 03:28:39 +10:00
sam d4df04f549 feat(edastore): project tool_call events into the tool_calls collection
The tool_calls collection existed in the event-capture schema but nothing
wrote it. Give it its write path:

- edastore gains InsertToolCall and the minimal TaskToolCalls read, writing
  only the existing collection. No new index: the collection is an
  append-only transcript and the SQLite predecessor had no unique index.
- internal/app/archied composes toolCallProjectingTaskStore, a decorator on
  the task store that persists the event first, then -- only for tool_call
  events -- writes one row. A projection failure is counted and logged but
  never returned from InsertEvent: event persistence is load-bearing,
  tool_calls is observability.
- stateStoreDeps wires the decorator around deps.Tasks when both stores are
  open, and passes Tasks through untouched otherwise.

The event adapts to the existing schema, not the other way round: the tool
name comes from data, a succeeded call's detail is the row's result, a
failed call's detail its error; args and duration_ms stay reserved for a
producer that reports them.
2026-09-23 03:26:14 +10:00
sam b9f1cf2260 merge(run/pb-ident): fail closed on an unresolvable task identity
Lane B. A task naming a non-empty identity this daemon no longer knows --
renamed, retired or deleted in the control plane -- used to fall back to the
root forge's credential. It now parks, and a NATS intake carrying one is
rejected before it is enqueued. An empty identity is the single-identity
root and still resolves to root.

Validation lives at the intake producer rather than in a foreign key:
tasks.identity uses '' as the valid root sentinel, so an FK would have to
admit '' as well as a real id, and turning on PRAGMA foreign_keys to make it
bite would also start enforcing the identity_aliases/identity_subjects FKs
that are decorative today -- wider than this change.
2026-09-23 03:24:41 +10:00
sam 6e635a2741 fix(daemon): fail closed on unresolvable task identity 2026-09-23 03:23:51 +10:00
sam da2589e2f4 chore(docs): regenerate dev-docs.json for the artifact-sender PRD
0e6c6fc6 added docs/prds/artifact-sender.md without regenerating the
artifact, so docs:artifact:check failed at that commit. Generated from a
clean worktree at 0e6c6fc6.
2026-09-23 03:16:35 +10:00
sam 0e6c6fc6d1 feat(artifacts): publish the completed PR review to the collaborative editor
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.
2026-09-23 03:15:27 +10:00
sam 8542f0d42c fix(proto): keep EventsSinceRequest.since_id's wire name
The cursor change renamed the field to 'cursor' as well as widening its
type, which buf breaking flags as FIELD_SAME_NAME and FIELD_SAME_JSON_NAME
on top of the type change. The name buys nothing: the field is already
documented as an opaque cursor, and the number and name are the wire
identity. Adopt the gate's verdict and change only the type, keeping the
break confined to the one rule already recorded in proto/buf.yaml.
2026-09-23 03:12:48 +10:00
sam 1bc009b3c5 merge(run/pb-cursor): generalise the event feed cursor to a total order
Lane A. EventsSince no longer relies on events.id being monotonic: it
orders by (at, id), where at is written in a fixed-width layout so
lexicographic order is chronological order, and id is only a
deterministic tie-break. The cursor crosses the wire as an opaque string
and rides the SSE id: field, so EventSource's own Last-Event-ID resume
keeps working untouched. A malformed or legacy cursor degrades to
"from the beginning" rather than failing the feed.

events.id keeps its int64 type and row-identity meaning; no
push/subscribe RPC is added.
2026-09-23 03:11:46 +10:00
sam ead8e4016d feat(store): generalise the event feed cursor to a total order
EventsSince no longer depends on events.id being monotonic. The feed now
pages a total order over (at, id): at is a fixed-width, lexicographically
sortable UTC timestamp (storecontract.EventCursorLayout) and id is only a
deterministic tie-break for rows sharing one timestamp. The cursor is an
opaque string on the wire (EventsSinceRequest.cursor), carried verbatim as
the SSE id: field and echoed back via Last-Event-ID, so EventSource resume
needs no client change.

A new idempotent migration normalises pre-existing RFC3339Nano at values to
the fixed-width layout before finishTaskMigration, and idx_events_at backs
the new query. Legacy integer and garbage cursors degrade to "from the
beginning", preserving the old failed-ParseInt-yields-0 behaviour.

Amends the "Dashboard live event delivery" decision's cursor-cannot-skip
justification, which previously rested on commit-order id assignment.
2026-09-23 03:10:30 +10:00
sam 630249f6d1 merge(run/pb-eda-realtime): announce binding and mapping edits on the activity stream
Lane C. A successful binding or mapping write on the State Store's
PocketBase tables now emits one activity event on the same task-DB path
capture arrival already uses, so a dashboard edit is visible on the
activity stream without a manual refresh.

The event is an invalidation signal, not a payload: it carries the record
id and the action, and consumers refetch through the authenticated API. A
nil notifier is a silent no-op, so stores composed without one (tests,
tooling) are unchanged.
2026-09-23 03:02:41 +10:00
sam 16b3fe6c6a chore(docs): regenerate dev-docs.json after the architecture doc move
docs:artifact:check has failed on this branch since e95a77c2 deleted
ARCHITECTURE.md and moved its normative content into docs/architecture;
the generated dev-docs artifact was never regenerated, so task check could
not pass. Regenerated from a clean tree (no untracked docs present).
2026-09-23 02:59:35 +10:00
sam 1132917593 fix(proto): record the deliberate int64->string break from the PocketBase migration
The event-capture contract moved its record ids from the SQLite rowid
(int64) to PocketBase's string record ids in place, on the same field
numbers: 16 fields across CapturedEvent, Mapping, Binding,
RecordDispatchRequest, EnqueueBindingTaskRequest, Task.binding_id and the
Id-bearing request/response messages. buf breaking has flagged them since
that commit landed, so task check has never passed on this branch.

Both halves of the State Store contract ship from this repository
together, so they cannot be versioned apart. Record the break narrowly:
only FIELD_SAME_TYPE is relaxed, and only for state/v1/state.proto. Every
other FILE rule still applies to that file and no other contract is
affected.
2026-09-23 02:59:03 +10:00
sam 408a3dcbb7 feat(edastore): announce binding and mapping edits on the activity stream
Each successful write on the State Store's PocketBase bindings/mappings
tables emits one event (binding_changed / mapping_changed) through a
nil-safe Notify func injected at composition, so a dashboard edit is
visible without a manual refresh -- the same task-DB event path capture
arrival uses. Nil notifier keeps every existing constructor silent.
2026-09-23 02:57:45 +10:00
sam bf36d57927 docs(scheduling): pin the pocketbase AND of day-of-month and day-of-week
tools/cron ANDs the two day fields where Vixie cron ORs them, so
0 0 1 * 1 means Monday the 1st, not the 1st or any Monday. State the
deviation in the ScheduleCron comment and pin it with a test.
2026-09-23 02:56:27 +10:00
sam d2aa680792 feat(scheduling): implement cron next-run arithmetic via pocketbase tools/cron 2026-09-23 02:53:39 +10:00
sam ed1557c12e feat(edastore)!: move event capture and bindings onto PocketBase collections
The event-capture tables (captures, mappings, bindings, binding_dispatches,
playbook_dispatches) now live in PocketBase-owned collections and their ids
are opaque record ids rather than autoincrement integers. The task lifecycle
stays on SQLite: tasks/transitions/events carry FIFO claim ordering, id-cursor
pagination and the task-grant map, none of which gain anything from being
hand-editable. binding_dispatches.task_id is the single seam and stays an
integer addressing that store.

BREAKING: CapturedEvent.Id, Mapping.Id, Binding.Id and Binding.MappingId are
strings on the wire, as are the ids in the capture/mapping/binding requests.
RecordDispatchRequest.task_id is deliberately unchanged.

What the collections buy, beyond storage: a payload nobody has modelled yet is
inspectable, a mapping is editable at runtime, and a binding's relation to its
mapping is enforced. The old schema declared no FOREIGN KEY on that link, so a
dangling mapping_id was previously possible and is now refused.

Behaviour preserved deliberately, each recovered from the SQLite version
rather than reimplemented from memory:
  - draft -> pending_approval -> armed, with approval only from
    pending_approval and an edit always returning a binding for re-approval
  - one binding per source, guarded on insert, update and approve
  - an empty secret on update keeps the stored one, so an edit form that does
    not echo it back cannot silently disarm a binding
  - ErrMappingNotFound / ErrBindingNotFound on a missing delete target
  - sentinels are re-exported from storecontract, never redefined: staterpc
    matches on exact canonical message to rehydrate them, so a second
    definition would break errors.Is across the wire invisibly

Two implementation notes worth keeping:
  - at-most-once dispatch is now a unique index rather than INSERT OR IGNORE.
    Only the unique-violation maps to ErrAlreadyDispatched; any other save
    error is returned, because treating them all as "already recorded" would
    turn the ledger into a silent at-least-once dispatcher.
  - captures store received_at themselves at nanosecond precision in a
    fixed-width layout. PocketBase autodates are millisecond and record ids
    are random, so same-millisecond captures would otherwise order
    arbitrarily; the old store got insertion order free from autoincrement.
  - ListUndispatchedCaptures is raw SQL: the anti-join is a subquery and
    PocketBase's filter DSL is not SQL. A read fires no hooks either way.

Adds tool_calls, which had no persistence at all: tool calls only ever reached
the on-disk task log, readable as text but never queryable or watchable.
Nothing writes it yet.

The binding secret cipher moves with the bindings it protects.
2026-09-23 02:19:28 +10:00
sam 0e94196052 refactor(scheduling): delete the legacy file-backed cronstore
The schedules feature no longer runs on it: jobs live in the state store
as the schedules control-plane document, read and written through the
control-plane client (scheduleResourceStore), and the legacy jobs.json
migration into that document has run its course. What remained of
internal/infrastructure/cronstore was 1,600 lines of file store, OS-level
cross-process locking and schema-versioned JSON envelope -- plus the
schedule vocabulary held hostage inside it.

The vocabulary moves to internal/domain/scheduling, which is where
migration-decisions already said a schedules vocabulary belongs: a domain
vocabulary package must not import infrastructure. JobSpec, Target,
Payload, the kind constants, Schedule and Duration move unchanged -- same
wire shape, same JSON tags -- with the two sentinel errors callers
matched outside the package (ErrJobNotFound, ErrScheduleUnsupported) and
ErrInvalidSpec, which the schedule arithmetic itself raises. The store's
own sentinels die with the store.

The legacy migration path (migrateLegacySchedules, readLegacyJobs) goes
with it: its only dependency was cronstore.Open, and its work is done.

crondelivery keeps its consumer-owned contracts; the compile-time
assertions that pinned *cronstore.Store move to the production
implementation, scheduleResourceStore, in internal/app/archied. The
package's fixtures swap the real file store for an in-memory one with
the same Get/MarkRun/Due semantics, so the run-recording acceptance test
still asserts against real schedule arithmetic.

A future storage backend (PocketBase) implements the same vocabulary.
2026-09-23 01:40:22 +10:00
sam 38eff78081 feat(edastore): PocketBase-owned collections for event capture and bindings
First slice of the persistence migration, taking the event-capture tables
rather than the task lifecycle. These five tables hold no production rows and
their feature (archie-core-t2db) is unfinished, so they migrate at zero data
risk and the remaining work lands natively instead of being written against
hand-rolled SQL and ported later. They are also the tables that actually want
what PocketBase gives: inspecting a payload nobody has modelled yet, mapping
fields against it, and editing a binding at runtime are the epic's acceptance
criteria, not incidental conveniences.

The task lifecycle deliberately stays on SQLite. tasks/transitions/events
carry FIFO claim ordering, id-cursor pagination and the task-grant map, none
of which gain anything from being hand-editable. binding_dispatches.task_id
is the single seam and stays a plain integer addressing that store.

Idempotency moves from INSERT OR IGNORE on a composite primary key to unique
indexes, so the at-most-once ledgers are enforced by the schema rather than by
each caller remembering the pattern. A save that fails for any other reason is
returned rather than swallowed: treating every error as "already recorded"
would turn a broken ledger into a silent at-least-once dispatcher.

Adds tool_calls, which had no persistence at all. Tool calls were only written
to the on-disk task log (internal/logging), readable as text but never
queryable, filterable or watchable.
2026-09-23 01:27:34 +10:00
sam c26536f067 fix(stateadmin): distinguish a missing collection from a failed lookup
Both collection lookups treated any error as "not present". For the users
collection that returned nil on a real failure (caught by nilerr); for the
views it was worse but unflagged, because creating a fresh view collection on
the strength of a transient lookup error is a schema change made for the wrong
reason. Only sql.ErrNoRows now means absent.
2026-09-23 00:56:24 +10:00
sam 1665f78e5b fix(stateadmin): drop the default users collection and pin the sqlite driver
PocketBase creates a "users" auth collection on first bootstrap whose
createRule is open, so an unauthenticated caller could POST a record and write
a row into the State Store's database file. This surface authenticates
superusers only and has no notion of end users, so the collection is deleted
rather than given a tighter rule: one that is absent cannot be loosened again
by a later PocketBase default.

Also re-applies the modernc pin. It was applied while developing the previous
commit but a concurrent go.mod resolution reverted it before that commit was
taken, so the tree has been running 1.59.0/1.77.1 against a PocketBase built
and tested on 1.57.0/1.74.4, printing the mismatch warning on every start.
Note for future dependency work: go get -u will undo this pin, and
modernc.org/libc does not follow semver, which is why PocketBase checks.

The claim in the previous commit message that the pin landed there is wrong.
2026-09-23 00:55:57 +10:00
sam d0af4832a6 feat(stateadmin): read-only operator dashboard over the State Store
Serve an optional PocketBase surface over archie.db from the process that
already owns it, behind archie-state-store -admin-addr. It co-tenants on
<db_path>-tasks.sqlite via PocketBase's DBConnect hook rather than opening a
database of its own, so the single-owner ownership claim covers it and
PRAGMA user_version stays archie's.

Every archie table is exposed as a view collection, which is read-only by
construction. Views alone do not hold that line: PocketBase also ships
POST /api/sql, which executes write statements as well as reads, and
/api/backups, which would put a second snapshot and restore semantics beside
store.Backup's VACUUM INTO. Both routes are refused rather than left behind a
superuser check, because a superuser writing task state is still a second
writer. The gRPC contract remains the only writer.

apis.NewRouter binds the JSON API but not the dashboard (apis.Serve mounts the
embedded UI itself), so /_/ is mounted here and the caller keeps the listener.

The dependency pin and the Taskfile/README changes for this landed with the
preceding commit, which swept up the staged files.
2026-09-23 00:37:15 +10:00
sam 6703cc77cf refactor(indexing): delete the workspace codesearch indexer
The index built google/codesearch over the chat workspace on every daemon
start, for the process lifetime, through a child-process helper and a
SQLite metadata DB -- and grep consulted it only for searches confined to
the workspace root, which the analysed sessions showed was a small
fraction of searches. The compute was continuous; the benefit was not.

Removes internal/indexing, the workspace-codesearch helper subcommand,
the [indexing] config section, and the GrepIndex accelerator seam from
the grep tool, which returns to its direct walk. google/codesearch
leaves go.mod with it.
2026-09-23 00:36:38 +10:00
sam e95a77c2f7 docs: delete ARCHITECTURE.md, move its normative content into docs/architecture
ARCHITECTURE.md duplicated the docs/architecture tree and had drifted badly
against it: "internal/ holds ~36" against 112 packages, two of the seven
binaries listed, a Forge table listing `RepliesAfter` (deleted from the tree),
and a stated invariant ("No daemon-internal cron") contradicted by the
scheduling engine that internal/app/archied/scheduling.go composes and
main.go starts.

It was also the sole home of three pieces of still-authoritative content, so
those move rather than disappear:

- plugin engine rule (strict), the memory engine family, and the
  internal/plugin/architecture_test.go enforcement note ->
  docs/architecture/plugins-and-extensions.md
- intake provenance: forge poll/webhook dedup through
  TaskEnvelope.IdempotencyKey, binding-stamped chat/playbook enqueue, and the
  single-identity webhook-intake rejection ->
  docs/architecture/messaging-and-work-intake.md

Live references are repointed from CLAUDE.md (AGENTS.md is a symlink to it),
docs/architecture, docs/guides, seven PRDs, and four .agents skills. The
heading "## Plugin engine rule (strict)" is preserved in its new home so the
existing #plugin-engine-rule-strict citations keep resolving. Generated docs
artifacts regenerated.
2026-09-22 23:49:53 +10:00
205 changed files with 10069 additions and 7661 deletions

No files matched your search

+1 -1
View File
@@ -158,7 +158,7 @@ Dolt remote is pushed explicitly (`bd dolt push`) and never assumed to be in syn
`.pi/control-plane-run/` holds a run's scaffold, lane plan, prompts, scripts and
gate output. It is gitignored and disposable. Treat it as run evidence only: a
fact worth keeping goes into this skill, `docs/`, or `ARCHITECTURE.md`, not into a
fact worth keeping goes into this skill or `docs/`, not into a
run directory the next clean deletes.
## Worked example
@@ -63,13 +63,13 @@ Do not simplify these facts into the target model:
| Workflow | `internal/domain/workflow` routes a `task.Task` into a `map[string]Workflow`, mutates a broad `TaskContext` through sequential stages. | `internal/domain/workflow/workflow.go` |
| Agent-stage boundary | Versioned `agentexec.Request`/`Result` carries one autonomous stage; validation correlates task, attempt, and stage. | `internal/agentexec/protocol.go` |
| Container handoff | `internal/taskrun` carries entire task plus `config.Repo` and `config.TaskConfig`; `internal/app/agentworker` owns routing and sequencing while its NATS adapter owns wire mechanics. | `internal/taskrun/taskrun.go`; `internal/app/agentworker/`; `internal/infrastructure/agenttransport/nats/` |
| Git ownership | Daemon-owned worktree operations clone, commit, push, diff, and clean up. | `internal/worktree/`; `internal/domain/workflow/steps.go`; `ARCHITECTURE.md` |
| Git ownership | Daemon-owned worktree operations clone, commit, push, diff, and clean up. | `internal/worktree/`; `internal/domain/workflow/steps.go`; `docs/architecture/agent-system.md` |
| Enforcement | Gates, read-only/protected paths, TDD inverted test gates, and diff caps are represented outside prompt prose. | `internal/gate/`; `internal/domain/workflow/{agent,tdd,steps}.go` |
| Configuration | `internal/config.Config`, `IdentityConfig`, `Repo`, and task snapshots mix input decoding with runtime concerns. Decoding itself lives in `internal/infrastructure/configuration`. | `internal/config/config.go`; `internal/infrastructure/configuration/` |
| Identity | Configured names and bot usernames act as process-local identity keys. There is no durable Identity domain. | `internal/daemon/daemon.go`; `internal/domain/storecontract/storecontract.go`; `internal/gateway/session.go` |
| Messaging | `internal/gateway` contains both the `Message` struct flow and richer `MessageEvent`; channel routing and task control are mixed with conversational behavior. | `internal/gateway/{gateway,messageevent,tasks}.go`; `internal/channels/` |
| Plugins | `plugin.Plugin` exposes only `Name` and `Version`; current loading interprets operator-installed Go files with Yaegi. | `internal/plugin/plugin.go` |
| Processes | Agent modes include in-process, subprocess, and NATS. Optional containers add a distinct boundary with known gaps. | `internal/config/config.go`; `internal/app/archied/`; `ARCHITECTURE.md` |
| Processes | Agent modes include in-process, subprocess, and NATS. Optional containers add a distinct boundary with known gaps. | `internal/config/config.go`; `internal/app/archied/`; `docs/architecture/organisation.md` |
### Interpret the current lifecycle honestly
@@ -98,13 +98,13 @@ not an open design.
| Invariant | Required action | Status and source |
| --- | --- | --- |
| The model never runs git | Keep clone, branch, commit, push, diff, and cleanup in deterministic workspace/worktree steps. | CURRENT: `ARCHITECTURE.md`; `internal/worktree/` |
| Deterministic constraints outrank prompts | Enforce gates, protected paths, read-only stages, test protection, and change caps outside model instructions. | CURRENT: `ARCHITECTURE.md`; `internal/gate/`; `internal/domain/workflow/` |
| Agent execution is a data boundary | Send bounded, versioned input; validate correlated output before applying it. | CURRENT foundation: `internal/agentexec/protocol.go`; `ARCHITECTURE.md` |
| The model never runs git | Keep clone, branch, commit, push, diff, and cleanup in deterministic workspace/worktree steps. | CURRENT: `docs/architecture/agent-system.md`; `internal/worktree/` |
| Deterministic constraints outrank prompts | Enforce gates, protected paths, read-only stages, test protection, and change caps outside model instructions. | CURRENT: `docs/architecture/agent-system.md`; `internal/gate/`; `internal/domain/workflow/` |
| Agent execution is a data boundary | Send bounded, versioned input; validate correlated output before applying it. | CURRENT foundation: `internal/agentexec/protocol.go`; `docs/architecture/agent-system.md` |
| Every workflow ends explicitly | Preserve terminal outcome or visible park. Preserve crash recovery of interrupted `running` work. | CURRENT: `internal/domain/workflow/workflow.go`; `internal/store/store.go` |
| Generic plugins stay metadata-only | Keep `plugin.Plugin` at `Name()`/`Version()`. Behavior on typed capability interface with owning `Registry`/`Manager`. | CURRENT-enforced rule: `internal/plugin/architecture_test.go` |
| Capability engines own lifecycle | Give resource-owning engines explicit start/health/stop semantics and failure isolation. | APPROVED rule: `ARCHITECTURE.md#plugin-engine-rule-strict` |
| Trust is explicit | Treat trusted operator-installed in-process code, repository code, out-of-process integrations, and container-isolated code as different trust classes. | APPROVED rule: `ARCHITECTURE.md#plugin-engine-rule-strict` |
| Capability engines own lifecycle | Give resource-owning engines explicit start/health/stop semantics and failure isolation. | APPROVED rule: `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict` |
| Trust is explicit | Treat trusted operator-installed in-process code, repository code, out-of-process integrations, and container-isolated code as different trust classes. | APPROVED rule: `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict` |
| Infrastructure stays replaceable | Keep forge, persistence, workspace, transport, container, and model details behind behavior-owned contracts. | APPROVED TARGET: `docs/architecture/dependencies-and-contracts.md` |
| Same-repository execution serializes by default | Preserve default unless explicit scheduling policy permits concurrency. | CURRENT: `internal/config/config.go`; `internal/daemon/daemon.go` |
+1 -1
View File
@@ -26,7 +26,7 @@ No root `README*` or `CONTRIBUTING*` file exists. Begin with:
```bash
sed -n '1,240p' CLAUDE.md
sed -n '1,240p' ARCHITECTURE.md
ls docs/architecture/
task --list
```
@@ -1,6 +1,6 @@
---
name: archie-docs-and-writing
description: Maintain Archie's documentation of record and write durable architecture decisions, migration plans, parity matrices, incident and dead-end records, feature ownership and deprecation records, operational runbooks, and documentation reviews. Use when deciding where an Archie fact belongs; reconciling code with ARCHITECTURE.md, CLAUDE.md, docs/prds, docs/archive, or generated contracts; changing tools/docsgen; documenting a feature so future maintainers can find its owners, consumers, invariants, superseded paths, deletion gates, evidence, and rollback; or checking documentation authority, drift, links, copied content, and source-artifact hygiene.
description: Maintain Archie's documentation of record and write durable architecture decisions, migration plans, parity matrices, incident and dead-end records, feature ownership and deprecation records, operational runbooks, and documentation reviews. Use when deciding where an Archie fact belongs; reconciling code with `CLAUDE.md`, `docs/architecture`, `docs/prds`, `docs/archive`, or generated contracts; changing `tools/docsgen`; documenting a feature so future maintainers can find its owners, consumers, invariants, superseded paths, deletion gates, evidence, and rollback; or checking documentation authority, drift, links, copied content, and source-artifact hygiene.
---
# Maintain Archie documentation
@@ -42,7 +42,6 @@ Verified on 2026-09-18:
|---|---|---|
| Live Go code, tests, `Taskfile.yml`, executable config parsing, composition under `internal/app/` (entered from `cmd/`) | `CURRENT` execution evidence | Trace producers and consumers; tests prove only asserted behavior |
| `CLAUDE.md` | Current contributor and safety protocol plus compact architecture orientation | Verify operational claims against code and `Taskfile.yml`; `AGENTS.md` is a symlink to it |
| `ARCHITECTURE.md` | Useful architecture history and partial current overview | Corroborate every inventory/status claim; its "Planned" list is stale for implemented skill support |
| `docs/prds/01-project-management.md` | Index and approved foundation for target architecture | Add or change target decisions in the focused document it names |
| `docs/architecture/*.md` | Focused target decisions, active review procedure, migration inventory | Read each file's status |
| `docs/architecture/migration-decisions.md` | `OPEN` migration inventory constrained by approved decisions | Close a question only after code-grounded review |
@@ -77,7 +76,7 @@ The repository root has no `README.md` or `CONTRIBUTING.md` as of 2026-09-18.
| Superseded design retained for context | `docs/archive/`, with historical status |
| Incident or rejected approach | `archie-failure-archaeology`'s chronology |
Do not duplicate a package map across `CLAUDE.md`, `ARCHITECTURE.md`, a PRD, and
Do not duplicate a package map across `CLAUDE.md`, a PRD, and
the site. Name the authoritative map and link to it.
## Write for future change
+90
View File
@@ -0,0 +1,90 @@
---
name: archie-web-ui
description: "Develop, review, or redesign archie-core's dashboard web UI (ui/). Load when adding or changing Vue components, pages, views, styling, theming, layout, or interaction patterns under ui/src; when auditing UI accessibility or contrast; or when porting design prototypes (e.g. React mockups) into the Vue dashboard. Carries stack facts, design-system rules, and the operational-tool tone required here."
---
# Web UI development (ui/)
Archie's dashboard is an **operational supervision tool** for senior developers
watching an autonomous orchestrator: quiet, dense, scannable, work-focused.
Not editorial, not marketing, not playful. Every rule below serves that.
## Stack facts (do not fight these)
- Vue 3 SFCs + TypeScript, Vite, Pinia, vue-router.
- Tailwind CSS v4 via `@tailwindcss/vite`; `@custom-variant dark` keyed on the
`[data-theme]` attribute; shadcn-vue + reka-ui for primitives;
`@lucide/vue` for icons; `@fontsource-variable/geist` is the typeface.
- Features live in `ui/src/<feature>/` with colocated `.js`/`.css`. Extract a
helper to `ui/src/base/` only on the **second distinct consumer**.
- `ui/dist/` is committed and generated — never hand-edit it, never ignore it
(see the header comment in `ui/src/style.css` for why builds are
content-coupled to the bundle).
- Gates: `task ui` (build), `task test:ui` (node --test over DOM-building
primitives in `ui/test/`), `vue-tsc` via `npm run typecheck`. `task check`
includes all of them.
- The dashboard is a LAW asset built from `ui/dist` — a Go-side embed. A UI
change is not done until `task ui` regenerates it and the commit carries it.
## Design-system rules
- **Tokens only.** Semantic CSS variables from `ui/src/style.css`
(`--primary`, `--ok`, `--muted`, ...). Never a raw hex in a component, never
a hue-named token. Dark is default; light defines the same variable set and
is a first-class theme, not an afterthought. Density is a single knob
(`[data-density="compact"]` tightens the spacing scale) — do not add
per-component density conditionals.
- **Icons, not text-as-decoration.** Buttons for clear commands use lucide
icons (icon-only where the symbol is familiar, with a tooltip naming it);
segmented controls for modes, toggles/checkboxes for binary settings,
selects/menus for option sets, tabs for views.
- **Cards 8px radius or less; no cards inside cards;** page sections are
full-width bands or unframed layouts, not floating cards. No gradient orbs,
bokeh blobs, or decorative backgrounds.
- **Stable dimensions.** Tables, tiles, toolbars, sparklines, and icon buttons
get fixed/constrained sizing so dynamic content (long titles, loading
states, big numbers) cannot shift layout. Text never overflows its
container on any viewport; wrap or downsize before it can.
- **No viewport-scaled font sizes, no negative letter-spacing.**
- **No one-note palettes.** If a screen reads as a single hue family
(e.g. all-violet), rebalance with neutrals and status colours rather than
more of the accent.
- **No in-app prose explaining the app** — no help text describing features,
keyboard shortcuts, or how to use a control. If a control needs explaining,
redesign the control.
- **No landing pages.** Every route opens the working experience directly.
## Tone & content
- Match copy to the domain: state names, gate results, timings, token counts —
concrete operational nouns, not conversational flourishes. A header states
system status ("Cluster operational · 4 awaiting intervention"), not a
greeting.
- Every human-actionable state (parked, gate failed, needs review) shows the
reason inline and links to the exact place to act on it (the failing log,
the gate output) — never just a status label.
- High-frequency background telemetry is grouped/summarised in activity feeds
("session-memory · 24 background cycles"), with high-signal events
(stage finished, gate failure, task parked) visually elevated.
## Accessibility bar
- WCAG AA minimum on all text: secondary/metadata labels must clear 4.5:1
against their actual background — audit the token, not the element. If a
muted token fails, fix the token value (one file), not individual spots.
- Log output, hashes, and code are monospace in a strict grid; do not put
rounded pill badges inside raw log lines (breaks monospace alignment).
Truncated stack traces fold into expandable blocks.
- Controls that filter or toggle (log level, wrap, follow, search) live in a
sticky toolbar inside the pane they affect.
## Porting design prototypes
External mockups (Gemini, Figma, React `.tsx` prototypes) are **specs, not
code**. This app is Vue; translate layout, hierarchy, and interaction
decisions into SFCs using shadcn-vue primitives and existing tokens. Mock data
in a prototype proves nothing — verify the pattern against real task/log/diff
shapes before building around it. A prototype proposing new information
architecture (e.g. splitting the task view into a master-detail pane) is an
open design question: it needs a decisive 1-page doc in `docs/prds/` before
structural work lands, per AGENTS.md.
+42 -15
View File
@@ -12,7 +12,7 @@ on:
# preceding fix, say) previously queued a full gate+build for each one,
# several minutes apiece, with no caching -- so a burst of pushes left
# three deploys racing in parallel for the same runner capacity. Only the
# last one's images matter (both jobs push :latest), so cancel a
# last one's images matter (each job pushes its image tags), so cancel a
# superseded run rather than let it fight for resources it can't use.
#
# Keyed on the commit, not github.ref: `git push --follow-tags` pushes
@@ -139,8 +139,8 @@ jobs:
echo "edit the generated notes, then: task release VERSION=<ver>"
exit 1
fi
if ! git tag --points-at HEAD | grep -qE 'archie' ; then
echo "::warning ::No release tags at HEAD, so this build publishes :latest for a commit that is not a release. It is stamped dev+<sha> and tagged sha-<sha> so it stays traceable and restorable, but it supersedes the previous release's :latest stamping until the next release is cut."
if ! git tag --points-at HEAD | grep -qE '^(v[0-9]|archied/v|archie/v)' ; then
echo "This commit is not a release, so the images are published as :edge and sha-<sha>; :latest keeps naming the newest release."
fi
build-and-push:
@@ -176,22 +176,51 @@ jobs:
run: |
GATEWAY_TAG="$(git tag --points-at HEAD --list 'archied/v*' | sort -V | tail -1)"
RUNTIME_TAG="$(git tag --points-at HEAD --list 'archie/v*' | sort -V | tail -1)"
# One release stream: a `v*` tag covers the whole release, so it names
# both components' versions. Legacy per-component tags still win where
# they exist, because history is not re-tagged.
RELEASE_TAG="$(git tag --points-at HEAD --list 'v*' | sort -V | tail -1)"
GATEWAY_VERSION="${GATEWAY_TAG#archied/}"
RUNTIME_VERSION="${RUNTIME_TAG#archie/}"
# Not a bare `dev`. A literal dev tells an operator nothing about which
# build they are running, and it is what made a release's stamping look
# transient: the next commit to main republished :latest as `dev`. The
# commit is appended so a main build is identifiable and is visibly not
# a release. (On an untagged push GITHUB_SHA IS the commit — the tag
# case is handled by the dereference above.)
[ -n "$GATEWAY_VERSION" ] || GATEWAY_VERSION="${RELEASE_TAG#v}"
[ -n "$RUNTIME_VERSION" ] || RUNTIME_VERSION="${RELEASE_TAG#v}"
# `dev+<sha>` is what a build that is NOT a release reports, and it is
# honest now that such a build no longer publishes :latest: the version
# names the commit it came from, and the sha-<sha> tag makes it
# restorable. Before, this same string reached :latest minutes after a
# release and made the release's own stamping read as dev
# (archie-core-i5nb). (On an untagged push GITHUB_SHA IS the commit —
# the tag case is handled by the dereference above.)
[ -n "$GATEWAY_VERSION" ] || GATEWAY_VERSION="dev+${GITHUB_SHA:0:12}"
[ -n "$RUNTIME_VERSION" ] || RUNTIME_VERSION="dev+${GITHUB_SHA:0:12}"
# Keep the raw tag presence separate from the version fallback:
# gateway-only releases must not rebuild the runtime image as dev.
# Keep the raw tag presence separate from the version fallback: a
# LEGACY gateway-only release (archied/v* and no archie/v*) must not
# rebuild the runtime image as dev. A one-stream `v*` release is not
# gateway-only -- one version covers the runtime too -- so it does
# rebuild it, and release_tag is what tells the two apart.
echo "gateway_tag=$GATEWAY_TAG" >> "$GITHUB_OUTPUT"
echo "runtime_tag=$RUNTIME_TAG" >> "$GITHUB_OUTPUT"
echo "release_tag=$RELEASE_TAG" >> "$GITHUB_OUTPUT"
echo "gateway=$GATEWAY_VERSION" >> "$GITHUB_OUTPUT"
echo "runtime=$RUNTIME_VERSION" >> "$GITHUB_OUTPUT"
# :latest names the newest RELEASE, so only a commit that IS one
# publishes it. A push to main publishes :edge (mutable, newest main)
# and sha-<sha> (immutable) instead. That is what stops a release's
# :latest stamping from being overwritten minutes later by the next
# ordinary commit, which left a host reporting dev and made the update
# path unable to tell current from stale (archie-core-i5nb).
#
# `if` blocks rather than `[ -n "$X" ] && echo`: the latter returns
# non-zero when the test fails, and these steps run under `set -e`.
{
echo "archied_tags<<EOF"
if [ -n "$RELEASE_TAG" ]; then
echo "ghcr.io/samcharles93/archied:latest"
fi
echo "ghcr.io/samcharles93/archied:edge"
echo "ghcr.io/samcharles93/archied:sha-${{ steps.commit.outputs.sha }}"
echo "EOF"
} >> "$GITHUB_OUTPUT"
- name: Build and push archied
uses: docker/build-push-action@v6
@@ -199,9 +228,7 @@ jobs:
context: .
file: Dockerfile.archied
push: true
tags: |
ghcr.io/samcharles93/archied:latest
ghcr.io/samcharles93/archied:sha-${{ steps.commit.outputs.sha }}
tags: ${{ steps.versions.outputs.archied_tags }}
build-args: |
GATEWAY_VERSION=${{ steps.versions.outputs.gateway }}
RUNTIME_VERSION=${{ steps.versions.outputs.runtime }}
@@ -209,7 +236,7 @@ jobs:
cache-to: type=gha,mode=max,scope=archied
- name: Build and push archie-agent
if: steps.versions.outputs.runtime_tag != ''
if: steps.versions.outputs.runtime_tag != '' || steps.versions.outputs.release_tag != ''
uses: docker/build-push-action@v6
with:
context: .
-436
View File
@@ -1,436 +0,0 @@
# archie-core Architecture
**archied** is a resident daemon that discovers forge work — GitHub and Gitea
issues assigned to its bot user, carrying its label, or either (`dispatch`
mode, per identity) — by polling (the default) or, single-identity
deployments only, reacting to forge webhook events the instant they arrive
(`Forge.Intake` = `webhook`/`both`, see `docs/prds/event-sources-and-
reactions.md`), works each matched issue in an isolated worktree through a
routed workflow, and opens pull requests for human review. A single daemon can
serve several identities across several forges, each with its own `bot_user`,
label, and repository set.
## Package Map
This lists the load-bearing packages, not all of them — `internal/` holds ~36.
The domain migration is in progress (`internal/domain/`,
`internal/infrastructure/`), so **the tree is authoritative over this table**.
See `docs/architecture/organisation.md` for the target structure and
`docs/architecture/migration-decisions.md` for the current position.
| Package | Role |
| ---------------------------- | ------------------------------------------------------------------------- |
| `cmd/archied/` | Binary entry: config→forge→store→runtime→workflows→daemon |
| `cmd/archie-agent/` | Binary entry: flags, environment, signals, and agentworker invocation |
| `internal/app/agentworker/` | Agent worker composition, lifecycle, routing, and workflow execution |
| `internal/infrastructure/agentboot/` | Worker boot-brief filesystem decoding |
| `internal/infrastructure/agentgit/` | Worker git safe-directory setup |
| `internal/infrastructure/agenttransport/nats/` | Worker core-NATS full-task handoff and RPC client construction |
| `internal/config/` | Config types only — loading lives in `infrastructure/configuration` |
| `internal/daemon/` | Resident loop: poll, enqueue, claim, route, process, reconcile |
| `internal/domain/workflow/` | Engine: stage lists, routing, shared steps, workflow definitions |
| `internal/domain/workflow/task/` | Task-execution vocabulary (`Task`, statuses, mid-run `Store`, `Definition`) importable without the engine |
| `internal/domain/messaging/` | Canonical messages plus the chat wire contracts (`ChatContract`, sessions, turns, streaming) shared by gateway, channels, webui, and archie-ui |
| `internal/channels/status/` | Operator-facing channel lifecycle ledger (`State`/`Descriptor`/`Status`/`Manager`); the plugin contract stays in `internal/channels` |
| `internal/app/archiemessaging/` | Messaging Service composition: Telegram/email/webhook channels, dialling the Gateway's `ChatContract` over gRPC. The daemon runs no channel and builds no `gateway.Router` |
| `internal/domain/workintake/`| `TaskEnvelope`, routing `Kind`, label vocabulary, task subjects |
| `internal/agentexec/` | Worker-local stage protocol and ai-sdk loop runner |
| `internal/forge/` | Forge interface: GitHub and Gitea implementations |
| `internal/forge/webhook/` | Optional forge webhook receiver: GitHub issue events → `workintake.TaskEnvelope`, same publish path as polling |
| `internal/webhookguard/` | Cross-cutting inbound-webhook mechanics: HMAC verification, per-source rate limiting |
| `internal/worktree/` | Git operations: clone, branch, commit, push, diff, cleanup |
| `internal/store/` | Task/capture/mapping/binding SQLite implementation; producer-owned contract interfaces live in `internal/domain/storecontract` (aliases kept here) |
| `internal/domain/storecontract/` | Producer-owned State Store read contracts consumed by webui, intake, and the gRPC adapters (state-store-contract rev. 2d) |
| `internal/events/` | In-process event bus: publish/subscribe for observability |
| `internal/infrastructure/` | Config loading, eventbus transport, model catalog |
| `internal/webui/` | Shared dashboard HTTP layer served by the archie-ui process |
| `internal/gateway/` (18.7k LOC) | Persistent-connection layer between archie and its users (Telegram, web UI, etc.); shared CommandRouter for dispatch |
| `internal/tools/` (20.9k LOC) | Central tool subsystem: built-in tool implementations, approval, execution contract |
| `internal/domain/memory/` | Memory engine contract: four typed scopes, CRUD + revisions, content scanner |
| `internal/infrastructure/memory/` | Builtin memory engine + its `builtin/` markdown store |
| `internal/secret/` | Secret reference resolution across named engines (env, vault, etc.) |
| `internal/plugin/` | Core plugin interface: Yaegi-interpreted `.go` plugins loaded from `~/.config/archie/plugins/` and registered with the daemon's extension registry |
| `internal/skill/` | Parses and discovers agentskills.io `SKILL.md` files |
| `ai-sdk/runtime` | External: provider-agnostic LLM runtime |
| `ai-sdk/agentloop` | External: gated agent loop with budgets and tool jails |
| `ai-sdk/core` | External: tool definitions, generate options |
## Task Lifecycle
```
queued → running(workflow:stage) → pr_open → merged | rejected
↓
waiting_human → (human approves) → queued(implement)
↓
parked
```
**Crash recovery:** tasks left in `running` are re-queued on startup. Parks are
never silent, but they no longer comment on the forge issue: the reason is
recorded on the task as `park_reason` (cleared on requeue) and surfaced by the
dashboard and `/api/tasks`. Retries are an explicit operator action capped by
`max_retries`, not a label a human removes.
**Adversarial review:** the implement workflow runs a fresh adversarial review
after the deterministic gates and before `pr_open` (see
`docs/architecture/adversarial-review.md`). A surviving blocking finding — or a
review that failed to run — parks the task with the findings as its
`park_reason`; otherwise the PR opens with a findings section on its body.
Opt-in per repo via `repo.review_enabled`.
**PR reconciliation:** the daemon polls open PRs, checks GitHub state
(`merged`/`closed`), transitions the task, and cleans up worktrees.
**Provenance by origin:** a task's origin determines which enqueue path
created it, though every origin converges on the same `tasks` table and the
same `Route`/`Run` lifecycle above once queued. Forge-sourced tasks — whether
discovered by polling or, single-identity only, delivered by the forge
webhook receiver (`internal/forge/webhook`) — enqueue via the same
`workintake.TaskEnvelope` and `PublishTask` path (see `docs/prds/event-sources-
and-reactions.md`'s decided contract); `TaskEnvelope.IdempotencyKey` is keyed
on `owner/repo/number`, not delivery source, so a webhook-delivered issue and
a later poll of the same issue dedup for free instead of double-enqueuing.
Playbook-binding-dispatched tasks enqueue
via `EnqueueChatTask`/`EnqueueBindingTask` (`internal/store`), the same direct
path chat-spawned tasks use, stamped with `binding_id`/`binding_version` for
provenance. See `docs/architecture/bindings.md` for the binding model and its
threat model in full.
## Workflow Engine
### Core types (`workflow.go`)
- `Workflow` = named list of `Stage`s
- `Stage` = `Name` + `Run(ctx, *TaskContext) error`
- `TaskContext` = mutable bag: Task, Repo, Config, Forge, Store, Agent runner,
worktree dir/branch, scratch fields
- `Outcome` = terminal decision (status + detail) -- ends the workflow
immediately
- `Registry` = `map[string]Workflow`
### Routing (`Route`)
Label-driven, no LLM involved. Pre-assigned workflow wins; then labels decide.
The built-in bindings are:
- `bug` → `tdd`
- `feature` → `feasibility`
- `bootstrap` → `bootstrap` (diagnostics, no LLM spend)
- Default → `implement`
Both the closed `bug`/`feature`/`bootstrap` set's target workflow and
arbitrary additional labels are YAML-overridable at daemon startup
(`internal/domain/workflow/routing.go`'s `LoadKindWorkflowsYAML`/
`LoadLabelWorkflowsYAML`, `WorkflowRoutingFile`/`WorkflowLabelsFile`/
`PlaybookDirs` config) -- see `docs/prds/eda-playbook-engine.md`. A label
already owned by the closed kind set, or a binding declared twice across
sources, is a reported load failure, not a silent override.
### Execution (`Run`)
Stages execute sequentially. After each stage:
- Task is persisted to SQLite
- Error → park the task (comment on issue, keep worktree)
- Outcome set → finish (transition task, update labels)
- Neither → continue to next stage
A workflow that ends without an outcome parks -- definition bugs must not vanish
silently.
## Workflows
### Bootstrap (diagnostics, no LLM)
```
prepare → apply(marker file) → commit-push → diff-cap → open-pr
```
Proves the plumbing: clone, push, PR. Label any test issue `bootstrap` to verify
end-to-end.
### Implement (default)
```
prepare → baseline-gate → plan(planner, read-only) → build(builder, gated) → commit-push → diff-cap → open-pr
```
- **baseline-gate:** runs the repo's gate at the base commit before anything is
touched
- **plan:** read-only agent explores codebase, produces implementation plan,
posts it as a comment
- **build:** full toolset agent implements against the plan behind the repo's
quality gate
- **diff-cap:** parks oversized changes (>400 lines default)
- **open-pr:** builder's summary becomes the PR body
### TDD (bug label)
```
prepare → baseline-gate → analyse(planner) → repro-tests(builder, inverted gate) → capture-proof → commit-repro → fix(builder, normal gate, test files protected) → commit-push → diff-cap → open-pr + repro-evidence
```
- **repro-tests:** the quality gate is **inverted** -- the test command must
FAIL. Proven failure is required.
- **capture-proof:** runs the test command deterministically, captures the
failing output
- **commit-repro:** commits the failing tests as the first commit
- **fix:** test files are **environmentally write-protected** (not
prompt-ruled). The agent fixes code, not tests.
- **open-pr + evidence:** posts both the PR and the captured failure proof
### Feasibility (feature label)
```
prepare → assess(planner, with decide tool) → [close_if_bad_fit | prd(planner)] → deliver → waiting_human
```
- **assess:** reads AGENT.md, ROADMAP.md, README. Calls a `decide` tool
(structured output, not parsed prose). Bad fit → close with reasons.
- **prd:** read-only agent writes a PRD: problem, solution, files affected,
acceptance criteria, non-goals, diff estimate
- **deliver:** posts PRD as issue comment + webhook notification (n8n → email).
Sets state to `waiting_human`.
- The daemon watches for human replies, judges them with a triage LLM
(APPROVE/REJECT/UNCLEAR), requeues or closes.
## Forge Interface
A thin abstraction over the forge. GitHub (`github.go`) and Gitea (`gitea.go`)
both implement it, plus a no-op (`noop.go`) used when no credential resolves —
see the degradation rule in `docs/architecture/configuration.md`. A multi-forge
deployment is configured per identity; see
`deployments/multi-forge-github-gitea.toml`.
| Method | Purpose |
| ------------------- | --------------------------------------- |
| `AcceptInvitations` | Auto-accept repo invites |
| `AssignedIssues` | Poll assigned issues (excluding PRs) |
| `IssuesWithLabel` | Poll labelled issues |
| `Comment` | Post issue/PR comment, return ID |
| `RepliesAfter` | Find human replies after a comment ID |
| `CreatePR` | Open pull request |
| `PRState` | Check merged/open/closed |
| `CloseIssue` | Close with final comment |
| `React` | Emoji reaction (pickup acknowledgement) |
| `SetStateLabel` | Replace old state label with new one |
| `VerifyPush` | Confirm push permission at startup |
State labels (`archie:queued`, `archie:working`, etc.) are created on demand,
removed when transitioning. They report state; they do not drive it. Removing
a label no longer retries a parked task -- retries are an explicit operator
action from the dashboard or chat, capped by `max_retries`.
### Webhook intake (alternative to polling)
`internal/forge/webhook` is a separate HTTP receiver, not a `Forge` method: it
verifies a GitHub webhook's HMAC signature (`internal/webhookguard.VerifyHMAC`),
decodes an `issues` event, applies the same dispatch predicate the poller
uses, and calls the same `PublishTask` the poller calls. It is opt-in via
`Forge.Intake` (`poll` default, `webhook`, `both`) and single-identity only: a
config naming `webhook`/`both` together with `[[identities]]`, or setting
intake on an identity, is rejected at validation rather than started with the
setting ignored -- the receiver binds one secret and one dispatch predicate,
so it cannot judge a second identity's events by the right rules. A
multi-identity deployment polls per identity until per-identity intake lands.
See `docs/prds/event-sources-and-reactions.md` for why this stayed a
thin decode-and-reuse layer rather than a second intake mechanism.
## Worktree Manager
Every task gets a fresh clone -- no persistent state between runs. The model
never runs git.
```
~/.local/share/archie/work/<owner>-<repo>/issue-<N>/
```
Token auth via a generated `GIT_ASKPASS` helper script -- the token never
appears in `.git/config` or process argv.
## Config
Daemon-level TOML (`~/.config/archie/config.toml`):
- `[forge]` -- type (github/gitea), host, token secret reference; `intake`
(`poll` default, `webhook`, or `both`) with `webhook_secret`/`webhook_addr`
when reacting to forge events instead of, or alongside, polling
(single-identity deployments only; rejected, not ignored, alongside
`[[identities]]` or on a `[identities.forge]` entry)
- `[dispatch]` -- trigger (assignee/label/either), labels, ack reaction
- `[[repos]]` -- owner, name, base branch, gate commands, protected paths,
ecosystem
- `[models]` -- planner, builder, triage (provider/model refs)
- `[providers]` -- LLM provider configs
- `[nats]` -- embedded or external broker deployment
- `[containers]` -- managed `archie-agent` image, limits, storage, and network
- `[budgets]` -- max steps, max tokens, wall clock, gate max failures
- `[web]` -- dashboard listen address, bound by the standalone archie-ui
process (the daemon runs no dashboard listener after the UI cutover)
- `[notify]` -- webhook URL for notifications
Secrets (forge token, provider API keys, channel tokens) are not embedded in
config files. `internal/secret` defines a pluggable `Engine` interface (`Name`,
`Version`, `Resolve(key) (string, error)`) resolved through a `Registry`; the
built-in `env` engine reads an environment variable by name and the built-in
`bws` engine caches the accessible Bitwarden project at startup. Custom engines
(sops, Vault/OpenBao) are Yaegi-interpreted `.go` plugins loaded from a
directory, following the same convention as `internal/plugin`'s daemon plugins.
Config fields reference a secret as
`{engine, key}` (`secret.SecretRef`), e.g.
`token = { engine = "env", key = "ARCHIE_GITHUB_TOKEN" }`. As of this writing
`Forge.Token` and `Provider.APIKey` use `SecretRef`; resolved provider values
are exported under private, identity-scoped environment names because the SDK
and container boundary consume credential names rather than
plaintext wire fields. The older `Provider.APIKeyEnv`, `NATSConfig.TokenEnv`, and
`TelegramConfig.TokenEnv` field names remain supported.
Per-repo gates are command lists: `[[repos.gate]] = ["go", "vet", "./..."]`. The
last command is the test runner (by convention -- TDD inverts it).
## Observability
Every lifecycle event flows through an internal event bus:
- SQLite event log (every event stamped with a row ID)
- Live dashboard via SSE (server-sent events)
- Bounded subscriber buffers -- slow consumers drop events, never block the
daemon
## Plugin engine rule (strict)
“Engine” is reserved for a typed, lifecycle-managed capability family. It is not
a synonym for a generic plugin hook. Every new plugin engine must satisfy all of
these invariants:
1. **Typed domain contract.** The engine interface exposes real
capability-specific operations in addition to identity metadata. Examples are
resolving a secret, delivering a message, or running an agent. A plugin that
only exposes `Name` and `Version` is metadata, not an engine.
2. **Owning family manager.** The capability package owns a `Registry` or
`Manager` that controls provider registration and discovery, initialization,
or access. Providers do not register arbitrary callbacks directly on the
daemon.
3. **Lifecycle and health.** When an implementation owns resources or background
work, its typed family contract must expose start, health, and stop
semantics. The owning manager invokes them and defines failure isolation and
shutdown ordering. Stateless providers may make these operations explicit
no-ops.
4. **Narrow host access.** Plugins receive the typed family registrar and only
the host services their declared capability requires. They never receive
`*daemon.Daemon`, a service locator, or an untyped hook map.
5. **Metadata-only generic plugin contract.** `plugin.Plugin` remains limited to
`Name()` and `Version()`. Domain hooks belong on typed engine interfaces;
adding capability methods to the generic interface is forbidden.
6. **Trust boundary stays explicit.** Explicitly trusted, operator-installed
plugins—including third-party secret-engine plugins the operator chooses to
trust—may run in-process and have daemon privileges. Repository-supplied code
runs in the task container. Integrations that are not trusted as daemon code
run out of process through MCP or a versioned protocol and, when a
confidentiality or integrity boundary is required, inside a real container
sandbox. A subprocess boundary alone is not a security sandbox, and calling
Yaegi-loaded code a plugin does not isolate it.
`internal/plugin/architecture_test.go` enforces the mechanically testable parts
of this rule: the generic plugin method set, the shared agent-instruction
source, and the requirement that engine interfaces have domain behavior plus an
owning registry or manager.
### Memory engine family
One engine, addressed by four typed scopes -- `ScopeGlobal`, `ScopeAgent`,
`ScopeUser`, `ScopeAgentUser` (`internal/domain/memory`, `Scope`/`ScopeKind`).
A caller names exactly the scopes it may read or write; the engine applies no
access policy of its own, so isolation falls out mechanically because
`ScopeAgent{a}` and `ScopeAgent{b}` are different storage keys. See
`docs/prds/memory-engine-unification.md` for the decision this contract
implements; it superseded `internal/memory` (`MemoryProvider`/`Manager`),
deleted in that PRD's slice 5.
`MemoryEngine` (`internal/domain/memory/contract.go`) is the typed family
contract: `Create`, `Get`, `Query`, `List`, `Update`, `Forget`, `Revisions` --
CRUD with revisions retained, not just create/read/delete. `Update` supersedes
rather than overwrites: the superseded state is appended to the scope's
`HISTORY.md` before the live block is replaced, and `Update` carries no
`Scope` field, so a record can never change scope. The family's content
scanner (prompt-injection / sensitive-data patterns) is applied inside
`Create` and `Update`, the single choke point every producer crosses.
`internal/domain/memory.Registry` is the owning family registry: registration,
start/health/stop, shutdown ordering, and failure isolation, following the
plugin engine rule (`ARCHITECTURE.md#plugin-engine-rule-strict`).
`internal/infrastructure/memory.NewBuiltinEngine` is the only registered
engine today; it persists through `internal/infrastructure/memory/builtin`,
a markdown store (`MEMORY.md`-shaped per-scope files) that owns its on-disk
format end-to-end.
Two per-turn seams in `internal/gateway` connect a chat turn to the engine,
each narrowed to exactly the operations it needs:
- **Read** (`turn_memory.go`, `MemoryStore`): `prepareTurn` runs a
scope-only `Query` over the resolved `Subject`'s readable scopes,
synchronously and before the prompt is built. It never returns an error --
a panicking or failing engine degrades to an empty `<memory>` block rather
than failing the turn -- and is bounded by a per-scope record limit and a
byte cap on the rendered block.
- **Write** (`turn_memory_tool.go`, `MemoryWriteStore`): four tools --
`memory_create`, `memory_update`, `memory_delete`, `memory_list` -- built
per turn onto the resolved `Subject`'s writable scopes, not registered once
at boot. The model chooses the scope kind; it never chooses the agent or
user id, which come from the turn's resolved `Subject` and have no schema
field to override. `ScopeGlobal` is never model-writable.
`boot.setupMemoryEngine` (`internal/app/archied/bootstrap.go`) registers and
starts the engine and must run before `setupGatewayChat`, which constructs the
only chat turn runner in production and captures the engine at construction
time (`internal/app/archied/composition_order_test.go` pins the ordering), and
before `setupCurators`, whose `Registrar` captures the engine registry. The session curator (`internal/infrastructure/sessioncurator`)
writes derived records onto `ScopeAgentUser`, making it the engine's other
live producer besides the chat write path.
## Key Design Decisions
1. **Environmental constraints over prompt rules.** The gate, test-file
protection, and diff cap are code enforcement -- not "please don't do that"
in the system prompt.
2. **The model never runs git.** Worktree operations are deterministic steps,
not agent tools.
3. **Tokens as cost, not features.** Token usage is tracked per task and emitted
in observability events but never budgeted beyond the agent loop's own
limits.
4. **Label-driven routing.** Workflow selection is a switch statement, not an
LLM call. A triage LLM is used only for the human reply judgment in
waiting_human.
5. **Shared code.** `ai-sdk/agentloop` and `ai-sdk/toolkit` provide the common
agent loop and tool set.
6. **No daemon-internal cron.** Polling is a ticker loop, not cron. The
feasibility PRD notification uses an external webhook (n8n).
7. **Fresh worktree per task.** No persistent state between runs. Crash recovery
just re-queues.
8. **Agent execution is a data boundary.** Autonomous stages receive a versioned
request and return a fenced result; SQLite, forge operations, git, workflow
sequencing, and outcome handling stay daemon-owned.
## What's Implemented vs Planned
**Implemented:**
- Daemon poll loop, enqueue, claim, process
- Forge webhook intake as a feature-flagged alternative/backstop pairing to
polling (single-identity deployments; see `internal/forge/webhook`)
- Bootstrap, implement, TDD, feasibility workflows
- GitHub and Gitea forges (issues, PRs, labels, comments, reactions)
- Worktree isolation (clone, branch, commit, push, diff, cleanup)
- SQLite store with transition audit
- Config with ecosystem support (go, python, node, rust)
- Agent stages with gates, budgets, preflight, protected paths
- Observability (event bus, SQLite log, SSE dashboard)
- Crash recovery (re-queue stale running tasks)
- Human reply judgment (triage LLM for waiting_human)
**Planned:**
- Multi-identity webhook intake (currently single-identity only)
- More ecosystems
- Notification integrations beyond n8n webhook
- Skills (SKILL.md support -- see `.archie/skills/`)
+130
View File
@@ -5,6 +5,136 @@ release's per-component sections are labelled beneath its heading.
## [Unreleased]
## [1.40.0] - 2026-09-23
### archied
- **Every park now says what kind of intervention it needs.** A parked task
is classified as `needs you` (a decision or fix only an operator can
supply), `transient` (an environment problem -- container pool, storage,
transport -- retry once it is fixed), or `terminal` (the repository or
identity cannot act; retrying cannot succeed). The class shows beside the
Parked badge on the dashboard, so "needs you" reads as a request rather
than a failure.
- **Operator retries and review-remediation rounds now have separate
budgets.** An operator's manual retries no longer draw down the rounds
Archie may spend addressing review feedback on its pull requests, and a
round-cap park no longer makes a later retry re-park immediately.
- **`latest` now names the newest release. A push to `main` that is not a
release publishes `edge` and `sha-<commit>` instead. A host that was
following `main` by pulling `latest` stops advancing at this release --
switch it to `edge` to keep tracking `main`, or leave it on `latest` to
follow releases.**
### archie-agent
- The park-classification wire format is part of this image; a host that
runs the agent should `docker compose pull agent` to pick it up.
## [1.39.0] - 2026-09-23
### archied
- **Archie now acts on review comments left on its own pull requests.** A
requested-changes review (or a standalone comment) on a PR Archie opened
dispatches a remediation run: the smallest change that satisfies the
feedback, committed to the same PR branch and answered in the review
thread. Approved reviews never remediate, each reaction is its own round,
and the exchange is bounded by the repo's `max_retries` before Archie stops
and says so on the PR.
- **The task run page is a master-detail view.** The run's stage rail and
detail panels sit beside the run list, so one run's timeline is visible
without leaving the page.
- **Live activity groups related updates instead of stacking them by event
kind**, so a burst of progress on one task reads as one story, and the
stage filter resets when you switch attempts.
- Contrast fixes on the info and subtle text tokens clear WCAG AA.
### archie-agent
- The review-reaction remediation path is part of this image; a host that
runs the agent should `docker compose pull agent` to pick it up.
## [1.38.0] - 2026-09-23
### archied — Event capture, mappings and bindings are PocketBase records
- **Captured events, field mappings and playbook bindings live in PocketBase
collections instead of SQLite tables.** They are ordinary records, which is
what lets a binding be changed at runtime rather than by editing a database.
- **A read-only operator surface over the task database ships with the State
Store** (`archie-state-store -admin-addr`). It serves view collections over
tasks, transitions, events, identities and resources, and refuses
`/api/backups` and `POST /api/sql`, so it cannot rewrite state or hand out the
database file.
- **A binding cannot go live without approval.** It moves draft → pending
approval → armed; one binding per source is enforced on insert, on edit and
on approval; and an edit always returns it to pending approval. A secret left
blank on an edit keeps the stored one rather than disarming a live binding.
- **The workspace code-search indexer is gone.** No deployment configured it,
and it was one more resident writer over the workspace.
### archied — Editing a binding or a mapping shows on the activity stream
- **A dashboard edit no longer needs a manual refresh.** A successful binding or
mapping write announces itself on the same activity path a captured event
already uses. The announcement carries the record id and the action and the
dashboard refetches the record, so the signal cannot go stale.
### archied — Cron schedules fire
- **A cron job computes its next run and fires.** Until this release a cron
schedule was accepted at creation and then refused at run time with
`ErrScheduleUnsupported`, so a cron job never ran.
- **The dialect is PocketBase's, and it differs from Vixie cron on one point.**
Day-of-month and day-of-week are combined with AND rather than Vixie's OR, so
`0 0 1 * 1` means Monday the 1st, not "the 1st, or any Monday". The
`@daily`-style macros behave as usual. An expression that can never match,
such as `0 0 30 2 *`, is rejected instead of being left to run forever.
### archied — Tool calls are queryable
- **Every completed tool call is a row in the `tool_calls` collection**, not
only a line in the on-disk task log. The row carries the task, the attempt,
the tool, its result or its error, and when it ran.
- **A failed projection never fails the task.** The event is the record and the
collection is a transcript of it, so a copy that could not be written is
logged and counted rather than propagated.
### archied — A task whose identity no longer resolves parks instead of acting as root
- **A task naming an identity archie no longer knows — renamed, retired or
removed in the control plane — no longer falls back to the root forge's
credential.** It parks with the reason recorded. A task arriving over NATS
with such an identity is refused before it is enqueued. A task with no
identity is the single-identity root path and is unchanged.
### archied — The PR review is published as a readable artifact
- **A completed review is rendered to markdown and published to the
collaborative editor**, so a person reads it and comments on it instead of
reading a wall of text in a pull-request comment.
- **Publishing never fails the review.** With `[artifacts] base_url` unset the
sender is not constructed and publishing is a log line; a publish that fails
is logged with its status and the same review is republished the next time it
completes. Set `[artifacts] token` (or `WORKSPACE_INGEST_TOKEN`) to enable it.
### archied — The activity feed no longer depends on row ids being monotonic
- **The feed's resume cursor is opaque, and a malformed or pre-upgrade cursor
degrades to "from the beginning" rather than failing the stream.** One
consequence on upgrade: a browser holding a cursor issued before this release
replays the backlog once.
### archie-agent
- **The runtime image is rebuilt by this release, and a host must pull it**
(`docker compose pull agent`). The shared State Store contract changed shape
in the sections above — task and event-capture id fields are strings now — and
the two halves are versioned together, so an agent image built before this
release does not speak to the new State Store. There are no agent behaviour
changes of its own in this release.
## [1.37.1] - 2026-09-22
### archied — A recorded event names the actor in its own fields
+17 -6
View File
@@ -25,11 +25,13 @@ assigned/labelled to it, works each one in an isolated git worktree through a
routed workflow (bootstrap / implement / TDD / feasibility), and opens pull
requests for human review.
See `ARCHITECTURE.md` for the package map, workflow engine design, task
lifecycle, and key design decisions. Read it before making non-trivial changes.
Key invariants: env-enforced gates, model never runs git, and agent execution
functions as a strict data boundary. Before adding a new plugin engine, satisfy
`ARCHITECTURE.md#plugin-engine-rule-strict`.
Architecture of record lives in `docs/architecture/` -- `organisation.md` for
the package map, `agent-system.md` for the workflow-execution lifecycle and its
invariants, `plugins-and-extensions.md` for engine families. Read it before
making non-trivial changes. Key invariants: env-enforced gates, model never runs
git, and agent execution functions as a strict data boundary. Before adding a new
plugin engine, satisfy
`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`.
## Scope Discipline
@@ -257,7 +259,8 @@ structures found in legacy packages.
- Webhook intake refuses to start when `[[identities]]` is configured (one
receiver, one dispatch config). Do not silently enable it for multi-identity
deployments without first building per-identity routing -- see
`ARCHITECTURE.md`'s "Webhook intake" section.
`docs/architecture/messaging-and-work-intake.md`'s "Intake provenance"
section.
- **`internal/domain/embedding/` + `internal/infrastructure/embedding/`:**
Embedding client contract + implementation. Config-driven exactly like chat
model roles: `models.embedding = "provider/model"` plus a `[providers.*]`
@@ -333,6 +336,14 @@ bd remember # Persist cross-session architectural facts
(`.gitignore`d, `export.auto: false`) -- never `git add` them and never
create a commit whose only content is beads bookkeeping. Bead state moves
through Dolt, not through git commits on this repo.
- **A bead never carries production instance detail.** No operator host name,
hostname, IP or port, filesystem path, PID, or credential -- in the body
*or* the title, since both sync to the Dolt remote and are therefore
published. Write the mechanism and the evidence shape instead ("a production
host", "the State Store target", "the host's `config.toml`"), and put the
host-specific facts in the operator's memos instance, which the bead may
point at. This is the same class of rule as never committing a credential:
the tracker is not a private store.
## Session Completion Protocol
+4 -2
View File
@@ -33,6 +33,8 @@ ARG GATEWAY_VERSION=dev
ARG RUNTIME_VERSION=dev
LABEL org.opencontainers.image.version="${GATEWAY_VERSION}"
LABEL cloud.catlow.archie.runtime-version="${RUNTIME_VERSION}"
COPY CHANGELOG.archied.md /usr/share/archie/CHANGELOG.archied.md
COPY CHANGELOG.archie.md /usr/share/archie/CHANGELOG.archie.md
# One release stream: CHANGELOG.md carries every release section, with each
# component's detail as a labelled section inside it. The per-component files
# this used to copy were deleted with the split release.
COPY CHANGELOG.md /usr/share/archie/CHANGELOG.md
ENTRYPOINT ["archied"]
+5
View File
@@ -76,6 +76,11 @@ Tagging one version produces, from a single `deploy` run:
`ghcr.io/samcharles93/archie-agent:latest`. The runtime image is rebuilt by the
release, so runtime commits merged to `main` do not reach a running sandbox until the
host pulls the new image.
- **`:latest` names the newest release, not the newest commit.** A push to `main`
that is not a release publishes `archied:edge` (mutable, tracking `main`) and
`archied:sha-<commit>` (immutable) instead, so a release's `:latest` stamping is
not overwritten minutes later by the next ordinary commit. A host that runs
releases follows `:latest`; a host that tracks `main` follows `:edge`.
- **A GitHub Release with a distribution zip** — `dist-zip` builds every process the
reference deployment runs (`archied`, `archie-gateway`, `archie-state-store`,
`archie-ui`, `archie-messaging`, `archie-playbooks`) for linux/amd64, packs them with
+22 -11
View File
@@ -350,6 +350,10 @@ tasks:
archie-gateway and archie-ui dial it -- none owns
the DB in-process
(docs/prds/state-store-contract.md §12 step 7)
* state admin read-only PocketBase surface over archie.db on
127.0.0.1:8686 (view collections only; the gRPC
contract stays the only writer). Served by the
archie-state-store process, not a sixth one.
* archie-ui serves the dashboard on 127.0.0.1:8484 from the
embedded dist (deployments/dev.toml). After the
UI cutover (archie-core-8cda.5.4) archied runs no
@@ -380,8 +384,12 @@ tasks:
dev:state-store:
desc: archie-state-store only, no live-reload (prefer `task dev`)
# -admin-addr serves the read-only operator dashboard over the same
# archie.db this process already owns. It is a flag rather than a config
# key for the same reason -ready-addr is: the address is a property of
# how this process was launched, not of the deployment's config document.
cmds:
- go run ./cmd/archie-state-store -config-overlay deployments/dev.toml
- go run ./cmd/archie-state-store -config-overlay deployments/dev.toml -admin-addr 127.0.0.1:8686
dev:gateway:
desc: archie-gateway only, no live-reload (prefer `task dev`)
@@ -431,17 +439,20 @@ tasks:
build:
desc: Build archie services and agent binaries
# Version stamping used to live only in Dockerfile.archied, so any build
# from source -- including a host deployment -- reported "dev" for
# both components and /version was useless there. Derive the same
# -X values from the release tags so a source build is stamped too.
# git describe (without --abbrev=0) yields 1.7.0-2-gbb54786 when HEAD is
# past the tag, which is the honest answer for a mid-cycle build.
# A from-source build is not a release, and CI is the only thing that stamps
# one: the version a release carries is written into the artifact CI
# publishes, the zip's binaries and the container image, and is never
# derived from whatever tags a local checkout happens to have.
#
# Deriving it here also made the stamp a function of the commit graph, which
# is the one input a content-checksum build cache cannot see: an empty
# commit moved `git describe` while `task build` still reported "up to date"
# and shipped the previous stamp (archie-core-pdq2). Stamping `dev` removes
# the non-file input rather than caching it, and a local build's
# traceability is the checkout it came from.
vars:
GATEWAY_VERSION:
sh: git describe --tags --match 'archied/v*' 2>/dev/null | sed 's|^archied/v||' || echo dev
RUNTIME_VERSION:
sh: git describe --tags --match 'archie/v*' 2>/dev/null | sed 's|^archie/v||' || echo dev
GATEWAY_VERSION: dev
RUNTIME_VERSION: dev
sources:
- "**/*.go"
- go.mod
+1
View File
@@ -39,6 +39,7 @@ func run() int {
flag.StringVar(&options.Listen, "listen", "", "state store gRPC listen address (defaults to [services.state].listen, else 127.0.0.1:9090)")
flag.StringVar(&options.Token, "token", "", "bearer token required for a non-loopback listener (defaults to [services.state].target_token)")
flag.StringVar(&options.ReadyAddr, "ready-addr", "", "optional readiness HTTP listen address (e.g. 127.0.0.1:9091)")
flag.StringVar(&options.AdminAddr, "admin-addr", "", "optional read-only operator dashboard listen address (e.g. 127.0.0.1:8090)")
flag.Usage = func() {
fmt.Fprintf(flag.CommandLine.Output(), "usage: archie-state-store [flags] # serve the State Store gRPC contract\n\noffline recovery: archie-state-store <backup|restore|validate|rollback> -h\n\n")
flag.PrintDefaults()
+7 -7
View File
@@ -372,8 +372,8 @@ func TestStateStoreRealProcessSmoke(t *testing.T) {
}); err != nil {
t.Fatalf("InsertEvent config_captured: %v", err)
}
if capID, err := cl.InsertCapture(ctx, capture("sentry", `{"id":1}`), 0, 0); err != nil || capID == 0 {
t.Fatalf("InsertCapture = (%d, %v)", capID, err)
if capID, err := cl.InsertCapture(ctx, capture("sentry", `{"id":1}`), 0, 0); err != nil || capID == "" {
t.Fatalf("InsertCapture = (%q, %v)", capID, err)
}
got, err := cl.TaskByID(ctx, task.ID)
@@ -583,8 +583,8 @@ func TestStateStoreRealProcessRemoteSurfaces(t *testing.T) {
ctx := t.Context()
mappingID, err := cl.InsertMapping(ctx, mapping.Mapping{Name: "m1", Fields: []mapping.Field{{Name: "a", Path: "a", Type: mapping.TypeString}}})
if err != nil || mappingID == 0 {
t.Fatalf("InsertMapping = (%d, %v)", mappingID, err)
if err != nil || mappingID == "" {
t.Fatalf("InsertMapping = (%q, %v)", mappingID, err)
}
if got, err := cl.GetMapping(ctx, mappingID); err != nil || got == nil || got.Name != "m1" {
t.Fatalf("GetMapping = %+v, %v", got, err)
@@ -593,8 +593,8 @@ func TestStateStoreRealProcessRemoteSurfaces(t *testing.T) {
Name: "b1", Matcher: binding.Matcher{Source: "sentry"}, MappingID: mappingID,
Workflow: "implement", Secret: "0123456789abcdef0123456789abcdef",
})
if err != nil || bindingID == 0 {
t.Fatalf("InsertBinding = (%d, %v)", bindingID, err)
if err != nil || bindingID == "" {
t.Fatalf("InsertBinding = (%q, %v)", bindingID, err)
}
// A binding starts as draft and must be edited (draft -> pending_approval)
// then approved (pending_approval -> armed) before it is armed for a
@@ -613,7 +613,7 @@ func TestStateStoreRealProcessRemoteSurfaces(t *testing.T) {
t.Fatalf("ArmedBindingsForSource = %+v, %v", armed, err)
}
// Remote surfaces share error-sentinel fidelity on the wire too.
missing := mapping.Mapping{ID: mappingID + 999999, Name: "x", Fields: []mapping.Field{{Name: "a", Path: "a", Type: mapping.TypeString}}}
missing := mapping.Mapping{ID: "rabsent00000000", Name: "x", Fields: []mapping.Field{{Name: "a", Path: "a", Type: mapping.TypeString}}}
if err := cl.UpdateMapping(ctx, missing); !errors.Is(err, store.ErrMappingNotFound) {
t.Fatalf("UpdateMapping missing = %v, want ErrMappingNotFound", err)
}
+5 -2
View File
@@ -37,6 +37,7 @@ import (
"github.com/samcharles93/archie-core/internal/domain/health"
"github.com/samcharles93/archie-core/internal/domain/messaging"
"github.com/samcharles93/archie-core/internal/domain/taskactions"
"github.com/samcharles93/archie-core/internal/infrastructure/edastore"
"github.com/samcharles93/archie-core/internal/infrastructure/gatewayrpc"
"github.com/samcharles93/archie-core/internal/infrastructure/staterpc"
"github.com/samcharles93/archie-core/internal/store"
@@ -601,8 +602,9 @@ func TestUIProcessLinksMultiIdentityTaskRowsToTheirOwningForge(t *testing.T) {
}
stateTarget, stopState := serveGRPC(t, func(r grpc.ServiceRegistrar) {
eda := edastore.OpenTest(t)
staterpc.RegisterServer(r, staterpc.Deps{
Tasks: st, Captures: st, BindingDispatcher: st, ConfigSnapshots: st,
Tasks: st, Captures: eda, BindingDispatcher: eda, ConfigSnapshots: st,
Log: slog.New(slog.DiscardHandler),
})
})
@@ -657,8 +659,9 @@ func TestUIProcessServesTheDashboardAgainstLiveDependencies(t *testing.T) {
gateway := &fakeGateway{}
stateTarget, stopState := serveGRPC(t, func(r grpc.ServiceRegistrar) {
eda := edastore.OpenTest(t)
staterpc.RegisterServer(r, staterpc.Deps{
Tasks: st, Captures: st, BindingDispatcher: st, ConfigSnapshots: st,
Tasks: st, Captures: eda, BindingDispatcher: eda, ConfigSnapshots: st,
Log: slog.New(slog.DiscardHandler),
})
})
-6
View File
@@ -15,11 +15,5 @@ func main() {
if archied.IsSetupArgs(args) {
os.Exit(archied.RunSetup(args[1:], os.Stdin, os.Stdout, os.Stderr))
}
// The codesearch helper is dispatched before the daemon's flags are
// parsed: it is this same binary re-invoked as a short-lived child by
// internal/indexing, and it must not touch config, the store or NATS.
if archied.IsCodesearchHelperArgs(args) {
os.Exit(archied.RunCodesearchHelper(args[1:], os.Stdout))
}
os.Exit(archied.Run())
}
+7 -6
View File
@@ -227,12 +227,13 @@ class = "ollama"
# work_dir = "/path/to/workspace"
# parallel_tool_calls = false
# Workspace code-search index. Paths default under work_dir when unset.
[indexing]
# Code-search index files (default: <work_dir>/indexes).
# index_dir = "/var/lib/archie/indexes"
# Per-index lifecycle metadata DB (default: <work_dir>/workspace-indexes.db).
# db_path = "/var/lib/archie/workspace-indexes.db"
# Publish artifacts (review reports, design docs) to the collaborative editor.
# An empty base_url disables publishing entirely. The token is runtime config:
# set WORKSPACE_INGEST_TOKEN in the daemon's environment or use a secret ref.
[artifacts]
# base_url = "https://offloaded.dev"
# token = { engine = "env", key = "WORKSPACE_INGEST_TOKEN" }
# token_env = "WORKSPACE_INGEST_TOKEN"
# archied's own liveness surface, always on. GET /healthz and /health answer
# 200 once the daemon is serving (503 while it is still booting), and
+41 -4
View File
@@ -8,15 +8,16 @@ import (
"testing"
)
func TestDeployWorkflowOnlyPublishesRuntimeImageForRuntimeTag(t *testing.T) {
func TestDeployWorkflowOnlyPublishesRuntimeImageForTaggedRelease(t *testing.T) {
source := readDeploymentFile(t, ".github/workflows/deploy.yml")
// The fallback remains necessary because Dockerfile.archied accepts a
// runtime version, but it must not be used as the image-publish selector.
for _, required := range []string{
`RUNTIME_TAG="$(git tag --points-at HEAD --list 'archie/v*' | sort -V | tail -1)"`,
`RELEASE_TAG="$(git tag --points-at HEAD --list 'v*' | sort -V | tail -1)"`,
`echo "runtime_tag=$RUNTIME_TAG" >> "$GITHUB_OUTPUT"`,
"if: steps.versions.outputs.runtime_tag != ''",
`echo "release_tag=$RELEASE_TAG" >> "$GITHUB_OUTPUT"`,
} {
if !strings.Contains(source, required) {
t.Errorf("deploy workflow is missing runtime-image guard %q", required)
@@ -24,13 +25,18 @@ func TestDeployWorkflowOnlyPublishesRuntimeImageForRuntimeTag(t *testing.T) {
}
// The gateway build remains unconditional, while the runtime build is
// guarded. This verifies both sides of the gateway-only/dual-tag contract.
// guarded. Both selectors are required. A one-stream release creates only a
// `v*` tag -- release.sh has no archie/v* arm any more -- so a
// runtime_tag-only condition would mean the agent image is never rebuilt
// again, and `docker compose pull agent` would fetch an ancient image
// forever. The legacy archie/v* arm stays because history is not re-tagged.
agentMarker := " - name: Build and push archie-agent\n"
agentStart := strings.Index(source, agentMarker)
if agentStart < 0 {
t.Fatal("deploy workflow has no archie-agent build step")
}
if !strings.Contains(source[agentStart:], agentMarker+" if: steps.versions.outputs.runtime_tag != ''\n") {
agentIf := " if: steps.versions.outputs.runtime_tag != '' || steps.versions.outputs.release_tag != ''\n"
if !strings.Contains(source[agentStart:], agentMarker+agentIf) {
t.Fatal("archie-agent build step is not conditionally enabled")
}
@@ -44,6 +50,37 @@ func TestDeployWorkflowOnlyPublishesRuntimeImageForRuntimeTag(t *testing.T) {
}
}
// TestDeployWorkflowPublishesLatestOnlyFromARelease pins the rule that keeps a
// release's :latest stamping from being overwritten by the next ordinary commit.
//
// build-and-push runs on any push to main and used to always push :latest, so a
// release's own stamping survived only until the next commit — minutes, in an
// active repo — and a host deploying :latest reported dev, leaving the update
// path unable to tell current from stale (archie-core-i5nb). :latest now moves
// only from a commit that IS a release; everything else publishes :edge and an
// immutable sha-<commit>.
func TestDeployWorkflowPublishesLatestOnlyFromARelease(t *testing.T) {
source := readDeploymentFile(t, ".github/workflows/deploy.yml")
for _, required := range []string{
`if [ -n "$RELEASE_TAG" ]; then`,
`echo "ghcr.io/samcharles93/archied:latest"`,
`echo "ghcr.io/samcharles93/archied:edge"`,
`archied_tags<<EOF`,
`tags: ${{ steps.versions.outputs.archied_tags }}`,
} {
if !strings.Contains(source, required) {
t.Errorf("deploy workflow is missing the release-only :latest guard %q", required)
}
}
// One occurrence: the guard above, not a second unconditional copy that would
// undo it.
if got := strings.Count(source, "ghcr.io/samcharles93/archied:latest"); got != 1 {
t.Errorf("archied :latest appears %d times, want exactly 1 inside the release-tag guard", got)
}
}
func TestDeployWorkflowUsesConfiguredFormatters(t *testing.T) {
source := readDeploymentFile(t, ".github/workflows/deploy.yml")
for _, required := range []string{
+18
View File
@@ -124,3 +124,21 @@ indicates dual-store ownership (`docs/prds/state-store-contract.md` §12 step 7/
The readiness probe is the single-writer check the runbook has against a
degraded store: a `503` from `/health/detailed` means `archied` should be
started only after the store is healthy.
### Inspecting the store
`-admin-addr` starts a read-only operator dashboard on the same process, over
the file it already owns:
```bash
archie-state-store -admin-addr 127.0.0.1:8686 # dashboard on http://127.0.0.1:8686/_/
```
It co-tenants on `<db_path>-tasks.sqlite` rather than opening a second
database, so it does not disturb the single-writer rule above: it runs inside
the process that holds the ownership claim, and every archie table is exposed
as a read-only view collection. The routes that could write past those views
(`POST /api/sql`, `/api/backups`) are refused, so the gRPC contract stays the
only writer and `archie-state-store backup` stays the only snapshot path.
Leave the flag off and no dashboard listener is started.
+3 -6
View File
@@ -5,9 +5,9 @@ through `.5`, `.7`, `.9`-`.15`)
**Date:** 2026-09-03
This document covers the binding model and the intake threat model portion
of `archie-core-t2db.6`. It does not cover the `ARCHITECTURE.md` task-lifecycle
addendum or the operator walkthrough -- those remain separate, open pieces of
the same ticket.
of `archie-core-t2db.6`. It does not cover the task-lifecycle provenance rule
(`messaging-and-work-intake.md`'s "Intake provenance") or the operator
walkthrough -- that walkthrough remains an open piece of the same ticket.
## What a binding is
@@ -177,9 +177,6 @@ execution-time idempotency, now landed (`archie-core-t2db.17` closed): the
## What this document does not cover
- The `ARCHITECTURE.md` task-lifecycle section noting that a
playbook-originated task has different provenance from a forge-issue
task -- open, part of `archie-core-t2db.6`.
- An end-to-end operator walkthrough (point an external app at archie,
build a first playbook) -- open, part of `archie-core-t2db.6`.
- The playbook YAML / CEL / Module/Channel/Forge action-position work
+2 -4
View File
@@ -58,7 +58,7 @@ survive as a shared package, configuration domain, or renamed global model.
Its loading behaviour moves to `internal/infrastructure/configuration`. Existing
types and methods are reassigned by behaviour. Repository execution policy,
dispatch policy, retry policy, ecosystem defaults, tool policy, memory settings,
indexing settings, provider settings, and channel settings move to their
provider settings, and channel settings move to their
respective owners.
## Repository settings
@@ -163,8 +163,7 @@ existing structure combines different owners.
| webhook target | `Notify` | Notification adapter instance settings. |
| web listen address | `Web` | Web transport settings. |
| `listen` under `[services.state]` and `[services.gateway]` | `ServiceConnection` | The bind address of the process that owns the service. Read only by that process, and defaulted to the address its clients dial so the pair cannot drift. |
| index directory and database path | `Indexing` | Index infrastructure settings, derived from storage settings unless explicitly overridden. |
| forge, dispatch, models, providers, containers, memory, tools, indexing and repositories | `IdentityConfig` | Existing composite duplicates unrelated settings. Replace it with associations from an `IdentityID` to independently owned configured instances. |
| forge, dispatch, models, providers, containers, memory, tools and repositories | `IdentityConfig` | Existing composite duplicates unrelated settings. Replace it with associations from an `IdentityID` to independently owned configured instances. |
| owner, name, base, gate, protection, ecosystem, preflight, storage, retry and concurrency | `Repo` | Split across work intake, workspace, workflow execution, policy, gate, and scheduling as described in Repository settings. |
| `TaskConfig`, `TaskForge` | worker snapshot | Replace with the minimum immutable, versioned WorkflowExecution input assembled by the application. It is not a second configuration model. |
| `Extra` and arbitrary maps | root/provider config | Allowed only at an extension boundary whose owning plugin/provider supplies schema and validation. Core configuration never consumes an untyped catch-all. |
@@ -187,7 +186,6 @@ decision; exact setting names are implementation details.
| NATS worker consumer | stream `ARCHIE_TASKS`, consumer `archie-agent`, deduplication `2m`, poll `5s`, acknowledgement wait `30m`, deliveries `3`, inactive threshold `24h`, queue group and retry delay `1s` | Worker transport settings and delivery/retry policy. Shared stream defaults must have one owner rather than two copies. |
| Worker readiness | readiness timeout `20s`, retry delay `250ms` | Worker lifecycle and retry policy. |
| Execution/RPC | agent execution `30m`, task-run RPC `60s`, worktree RPC `15m` | Per-operation timeout policy. |
| Indexing | build timeout `10m`, metadata timeout `5s` | Index operation policy. |
| Plugin/tool cleanup | plugin rollback `10s`, tool-provider cleanup `10s`, MCP-provider cleanup `10s` | Lifecycle shutdown/rollback policy owned by each engine, with a shared policy vocabulary where appropriate. |
| Memory read path | per-scope record limit `20`, rendered `<memory>` block byte cap `8192` | Memory read policy owned by the engine family (`internal/domain/memory`). |
| Built-in memory store | per-file size limit `100KiB`, query result limit `100` | Split into memory resource policy, input policy, and presentation settings. |
@@ -251,6 +251,32 @@ Current intake is fragmented:
- `store.Task` collapses an external source reference and durable execution
state.
## Intake provenance
A task's origin determines which enqueue path created it, though every origin
converges on the same `tasks` table and the same `Route`/`Run` lifecycle once
queued.
- Forge-sourced work -- discovered by polling or, in single-identity
deployments, delivered by the forge webhook receiver (`internal/forge/webhook`)
-- enqueues through the same `workintake.TaskEnvelope` and `PublishTask` path.
`TaskEnvelope.IdempotencyKey` is keyed on `owner/repo/number` and not on the
delivery source, so a webhook-delivered issue and a later poll of the same
issue dedup through `PublishUnique` instead of double-enqueuing.
- Chat-spawned and playbook-binding-dispatched work enqueues through
`EnqueueChatTask`/`EnqueueBindingTask` (`internal/store`), stamped with
`binding_id`/`binding_version` for provenance.
Webhook intake is opt-in per deployment (`Forge.Intake` = `poll` (default),
`webhook`, or `both`) and single-identity only: a config naming
`webhook`/`both` alongside `[[identities]]`, or setting intake on a
`[identities.forge]` entry, is rejected at validation rather than started with
the setting ignored. One receiver binds one secret and one dispatch predicate,
so it cannot judge a second identity's events by the right rules. A
multi-identity deployment polls per identity until per-identity intake lands.
The decided contract is `docs/prds/event-sources-and-reactions.md`; the binding
model and its threat model are `docs/architecture/bindings.md`.
## Current hazards
- Treating every agent interaction as a work request would remove Archie's
+4 -3
View File
@@ -264,9 +264,10 @@ around is no longer a boundary.
returns and validates `workflow.ExecutionSettings`, so any package holding it
links the workflow domain and therefore `internal/agentexec`. This is why the
client cannot move as one package -- see open question 2.
- The schedules document, whose type is `cronstore.JobSpec` in
`internal/infrastructure`. A domain vocabulary package may not import
infrastructure.
- The schedules document, whose type is `scheduling.JobSpec` in
`internal/domain/scheduling` -- the vocabulary moved there when the legacy
file-backed cronstore was deleted, which is also what satisfies the rule
that a domain vocabulary package may not import infrastructure.
- The schema derivation, which describes the documents the server advertises.
**Placement as landed (2026-09-22, `archie-core-1ng1`).** One new package,
+94 -2
View File
@@ -23,6 +23,97 @@ versioning, definition, and execution contracts. The generic plugin domain may
provide plugin identity, discovery, compatibility, and lifecycle mechanics, but
it MUST NOT define Workflow semantics or expose untyped Workflow hooks.
## Plugin engine rule (strict)
“Engine” is reserved for a typed, lifecycle-managed capability family. It is not
a synonym for a generic plugin hook. Every new plugin engine must satisfy all of
these invariants:
1. **Typed domain contract.** The engine interface exposes real
capability-specific operations in addition to identity metadata. Examples are
resolving a secret, delivering a message, or running an agent. A plugin that
only exposes `Name` and `Version` is metadata, not an engine.
2. **Owning family manager.** The capability package owns a `Registry` or
`Manager` that controls provider registration and discovery, initialization,
or access. Providers do not register arbitrary callbacks directly on the
daemon.
3. **Lifecycle and health.** When an implementation owns resources or background
work, its typed family contract must expose start, health, and stop
semantics. The owning manager invokes them and defines failure isolation and
shutdown ordering. Stateless providers may make these operations explicit
no-ops.
4. **Narrow host access.** Plugins receive the typed family registrar and only
the host services their declared capability requires. They never receive
`*daemon.Daemon`, a service locator, or an untyped hook map.
5. **Metadata-only generic plugin contract.** `plugin.Plugin` remains limited to
`Name()` and `Version()`. Domain hooks belong on typed engine interfaces;
adding capability methods to the generic interface is forbidden.
6. **Trust boundary stays explicit.** Explicitly trusted, operator-installed
plugins—including third-party secret-engine plugins the operator chooses to
trust—may run in-process and have daemon privileges. Repository-supplied code
runs in the task container. Integrations that are not trusted as daemon code
run out of process through MCP or a versioned protocol and, when a
confidentiality or integrity boundary is required, inside a real container
sandbox. A subprocess boundary alone is not a security sandbox, and calling
Yaegi-loaded code a plugin does not isolate it.
`internal/plugin/architecture_test.go` enforces the mechanically testable parts
of this rule: the generic plugin method set, the shared agent-instruction
source, and the requirement that engine interfaces have domain behavior plus an
owning registry or manager.
### Memory engine family
One engine, addressed by four typed scopes -- `ScopeGlobal`, `ScopeAgent`,
`ScopeUser`, `ScopeAgentUser` (`internal/domain/memory`, `Scope`/`ScopeKind`).
A caller names exactly the scopes it may read or write; the engine applies no
access policy of its own, so isolation falls out mechanically because
`ScopeAgent{a}` and `ScopeAgent{b}` are different storage keys. See
`docs/prds/memory-engine-unification.md` for the decision this contract
implements; it superseded `internal/memory` (`MemoryProvider`/`Manager`),
deleted in that PRD's slice 5.
`MemoryEngine` (`internal/domain/memory/contract.go`) is the typed family
contract: `Create`, `Get`, `Query`, `List`, `Update`, `Forget`, `Revisions` --
CRUD with revisions retained, not just create/read/delete. `Update` supersedes
rather than overwrites: the superseded state is appended to the scope's
`HISTORY.md` before the live block is replaced, and `Update` carries no
`Scope` field, so a record can never change scope. The family's content
scanner (prompt-injection / sensitive-data patterns) is applied inside
`Create` and `Update`, the single choke point every producer crosses.
`internal/domain/memory.Registry` is the owning family registry: registration,
start/health/stop, shutdown ordering, and failure isolation, following the
plugin engine rule above. `internal/infrastructure/memory.NewBuiltinEngine` is
the only registered engine today; it persists through
`internal/infrastructure/memory/builtin`, a markdown store (`MEMORY.md`-shaped
per-scope files) that owns its on-disk format end-to-end.
Two per-turn seams in `internal/gateway` connect a chat turn to the engine,
each narrowed to exactly the operations it needs:
- **Read** (`turn_memory.go`, `MemoryStore`): `prepareTurn` runs a
scope-only `Query` over the resolved `Subject`'s readable scopes,
synchronously and before the prompt is built. It never returns an error --
a panicking or failing engine degrades to an empty `<memory>` block rather
than failing the turn -- and is bounded by a per-scope record limit and a
byte cap on the rendered block.
- **Write** (`turn_memory_tool.go`, `MemoryWriteStore`): four tools --
`memory_create`, `memory_update`, `memory_delete`, `memory_list` -- built
per turn onto the resolved `Subject`'s writable scopes, not registered once
at boot. The model chooses the scope kind; it never chooses the agent or
user id, which come from the turn's resolved `Subject` and have no schema
field to override. `ScopeGlobal` is never model-writable.
`boot.setupMemoryEngine` (`internal/app/archied/bootstrap.go`) registers and
starts the engine and must run before `setupGatewayChat`, which constructs the
only chat turn runner in production and captures the engine at construction
time (`internal/app/archied/composition_order_test.go` pins the ordering), and
before `setupCurators`, whose `Registrar` captures the engine registry. The
session curator (`internal/infrastructure/sessioncurator`) writes derived
records onto `ScopeAgentUser`, making it the engine's other live producer
besides the chat write path.
## Plugin implementations
First-party plugins are self-contained vertical modules under
@@ -48,8 +139,9 @@ in-process through typed capability families (this document's model) or
out-of-process like a generic `DispatchEvent` dispatcher. Decided 2026-08-22
in `docs/prds/event-sources-and-reactions.md`: in-process typed families,
confirming this document's model rather than amending it. The forge webhook
receiver (`internal/forge/webhook`, see `ARCHITECTURE.md`'s "Webhook intake"
section) and the EDA playbook engine's Module action position
receiver (`internal/forge/webhook`; see "Intake provenance" in
`docs/architecture/messaging-and-work-intake.md`) and the EDA playbook engine's
Module action position
(`docs/prds/eda-playbook-engine.md`, `internal/domain/eda/module`) are the
shipped instances of that decision -- each is a narrow typed contract with an
owning registry, not a generic event hook. The playbook engine's Channel and
+33 -13
View File
@@ -22,13 +22,13 @@
"url": "/dev/architecture/bindings/",
"title": "Playbook bindings: model and threat model",
"section": "Architecture",
"body": "# Playbook bindings: model and threat model\n\n**Status:** Approved foundation (documents shipped code: `archie-core-t2db.1`\nthrough `.5`, `.7`, `.9`-`.15`)\n**Date:** 2026-09-03\n\nThis document covers the binding model and the intake threat model portion\nof `archie-core-t2db.6`. It does not cover the `ARCHITECTURE.md` task-lifecycle\naddendum or the operator walkthrough -- those remain separate, open pieces of\nthe same ticket.\n\n## What a binding is\n\nA `binding` (`internal/domain/binding.Binding`) ties four things together:\na **matcher** (which captured events it applies to), a **mapping**\n(`internal/domain/mapping.Mapping`, how fields are pulled out of a payload),\na **workflow** (which registered workflow runs on a match), and a **state\nmachine** governing whether it is live.\n\n```go\ntype Binding struct {\n ID, Name // identity\n Matcher // { Source string } -- the webhook path segment, e.g. \"sentry\"\n MappingID // which Mapping resolves payload fields\n Workflow // registered workflow name to dispatch to\n Version // bumped on every edit\n Status // draft | pending_approval | armed\n Secret // HMAC-SHA256 shared secret, encrypted at rest, never returned by GET\n}\n```\n\nBindings live in the store (SQLite), not `config.toml` -- operators author\nthem from the dashboard while the daemon runs, without a restart.\n\n### Matching\n\n`Matcher.Source` is the only predicate today: the path segment a sender\nPOSTs to (e.g. a webhook hitting `.../sentry` matches bindings with\n`Matcher.Source == \"sentry\"`). The storage column is plain `TEXT`, so adding\npredicates later is non-breaking -- extend `Matcher`, don't invent a second\nmatcher shape.\n\n### Mapping\n\n`mapping.Resolve(fields, payload)` walks a captured JSON payload against a\nlist of typed `Field`s (name, JSON path, expected type), returning resolved\nvalues plus a `[]Failure` for anything that didn't parse or type-match. This\nis schema-by-example in practice: a mapping is authored by pointing at a\nreal captured payload in the dashboard, not by guessing a schema in advance.\n\n### Versioning\n\n`Version` increments on every `UpdateBinding` call. This exists so an\neditor's later change can never silently rewrite the historical provenance\nof a task that already fired -- a dispatched task's binding reference is\npinned to the version that was armed when it fired, not \"whatever the\nbinding currently says.\"\n\n### State machine\n\n```\ndraft ---\u003e pending_approval ---\u003e armed\n ^ ^ |\n | | |\n +--------------+-----------------+\n (any edit to an armed binding drops it back to pending_approval)\n```\n\nModeled directly on Telegram's existing `dangerousAction`/`pendingApproval`\nflow (`internal/channels/telegram/dangerous.go`, `approval.go`) -- not a new\napproval mechanism invented for this feature. **Only `armed` evaluates\nagainst incoming events** (`binding.Matches`, `internal/domain/binding/\nbinding.go`); `draft` and `pending_approval` bindings are inert. An edit to\nan already-armed binding cannot bypass approval by silent mutation -- it\ndrops back to `pending_approval` and requires an explicit `Approve` call to\nre-arm.\n\n## The threat model\n\nThis is a public, unauthenticated-by-default intake surface whose output is\nan agent with a repo, a worktree, and tool access. The design brief\n(`archie-core-t2db.5`, `docs/prds/webhook-intake-security.md`) named five\nnon-negotiables; each is verified below against the actual shipped code,\nnot the design intent.\n\n### 1. Per-source authentication\n\nReuses `internal/channels/webhook`'s existing HMAC-SHA256 scheme --\ncapture accepts unsigned events (visible in the dashboard, marked\nunauthenticated), but **only authenticated events can ever match a\nbinding**. `binding.Matches`' doc comment states this plainly: \"an\nunauthenticated event can never trigger a binding, no matter how well it\nwould otherwise match.\" Enforced structurally at two points, not just\nconvention:\n\n- `captured_events.authenticated` is a real column (`internal/store/\n captures.go`), set at capture time.\n- `dispatchBindings` (`internal/daemon/daemon.go:479`) walks **authenticated\n captures whose source has at least one armed binding** -- an\n unauthenticated capture is never even considered for dispatch.\n\n### 2. Human approval before a binding goes live\n\nCovered by the state machine above. Nothing self-arms: `pending_approval -\u003e\narmed` requires an explicit `Approve` call, and any edit to an armed\nbinding reverts it.\n\n### 3. Rate and volume limits per source\n\nCapture writes are bounded independently of the approval gate, so a flood\nof unauthenticated traffic cannot exhaust disk or drown the inspector:\n`InsertCapture` (`internal/store/captures.go`) prunes by both **retention\nwindow** (`WHERE received_Line truncated
"body": "# Playbook bindings: model and threat model\n\n**Status:** Approved foundation (documents shipped code: `archie-core-t2db.1`\nthrough `.5`, `.7`, `.9`-`.15`)\n**Date:** 2026-09-03\n\nThis document covers the binding model and the intake threat model portion\nof `archie-core-t2db.6`. It does not cover the task-lifecycle provenance rule\n(`messaging-and-work-intake.md`'s \"Intake provenance\") or the operator\nwalkthrough -- that walkthrough remains an open piece of the same ticket.\n\n## What a binding is\n\nA `binding` (`internal/domain/binding.Binding`) ties four things together:\na **matcher** (which captured events it applies to), a **mapping**\n(`internal/domain/mapping.Mapping`, how fields are pulled out of a payload),\na **workflow** (which registered workflow runs on a match), and a **state\nmachine** governing whether it is live.\n\n```go\ntype Binding struct {\n ID, Name // identity\n Matcher // { Source string } -- the webhook path segment, e.g. \"sentry\"\n MappingID // which Mapping resolves payload fields\n Workflow // registered workflow name to dispatch to\n Version // bumped on every edit\n Status // draft | pending_approval | armed\n Secret // HMAC-SHA256 shared secret, encrypted at rest, never returned by GET\n}\n```\n\nBindings live in the store (SQLite), not `config.toml` -- operators author\nthem from the dashboard while the daemon runs, without a restart.\n\n### Matching\n\n`Matcher.Source` is the only predicate today: the path segment a sender\nPOSTs to (e.g. a webhook hitting `.../sentry` matches bindings with\n`Matcher.Source == \"sentry\"`). The storage column is plain `TEXT`, so adding\npredicates later is non-breaking -- extend `Matcher`, don't invent a second\nmatcher shape.\n\n### Mapping\n\n`mapping.Resolve(fields, payload)` walks a captured JSON payload against a\nlist of typed `Field`s (name, JSON path, expected type), returning resolved\nvalues plus a `[]Failure` for anything that didn't parse or type-match. This\nis schema-by-example in practice: a mapping is authored by pointing at a\nreal captured payload in the dashboard, not by guessing a schema in advance.\n\n### Versioning\n\n`Version` increments on every `UpdateBinding` call. This exists so an\neditor's later change can never silently rewrite the historical provenance\nof a task that already fired -- a dispatched task's binding reference is\npinned to the version that was armed when it fired, not \"whatever the\nbinding currently says.\"\n\n### State machine\n\n```\ndraft ---\u003e pending_approval ---\u003e armed\n ^ ^ |\n | | |\n +--------------+-----------------+\n (any edit to an armed binding drops it back to pending_approval)\n```\n\nModeled directly on Telegram's existing `dangerousAction`/`pendingApproval`\nflow (`internal/channels/telegram/dangerous.go`, `approval.go`) -- not a new\napproval mechanism invented for this feature. **Only `armed` evaluates\nagainst incoming events** (`binding.Matches`, `internal/domain/binding/\nbinding.go`); `draft` and `pending_approval` bindings are inert. An edit to\nan already-armed binding cannot bypass approval by silent mutation -- it\ndrops back to `pending_approval` and requires an explicit `Approve` call to\nre-arm.\n\n## The threat model\n\nThis is a public, unauthenticated-by-default intake surface whose output is\nan agent with a repo, a worktree, and tool access. The design brief\n(`archie-core-t2db.5`, `docs/prds/webhook-intake-security.md`) named five\nnon-negotiables; each is verified below against the actual shipped code,\nnot the design intent.\n\n### 1. Per-source authentication\n\nReuses `internal/channels/webhook`'s existing HMAC-SHA256 scheme --\ncapture accepts unsigned events (visible in the dashboard, marked\nunauthenticated), but **only authenticated events can ever match a\nbinding**. `binding.Matches`' doc comment states this plainly: \"an\nunauthenticated event can never trigger a binding, no matter how well it\nwould otherwise match.\" Enforced structurally at two points, not just\nconvention:\n\n- `captured_events.authenticated` is a real column (`internal/store/\n captures.go`), set at capture time.\n- `dispatchBindings` (`internal/daemon/daemon.go:479`) walks **authenticated\n captures whose source has at least one armed binding** -- an\n unauthenticated capture is never even considered for dispatch.\n\n### 2. Human approval before a binding goes live\n\nCovered by the state machine above. Nothing self-arms: `pending_approval -\u003e\narmed` requires an explicit `Approve` call, and any edit to an armed\nbinding reverts it.\n\n### 3. Rate and volume limits per source\n\nCapture writes are bounded independently of the approval gate, so a flood\nof unauthenticated traffic cannot exhaust disk or drown the inspector:\n`InsertCapture` (`internal/store/captures.go`) prunLine truncated
},
{
"url": "/dev/architecture/configuration/",
"title": "Configuration",
"section": "Architecture",
"body": "# Configuration\n\n**Status:** Approved; existing-type assignment is ongoing \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Ownership\n\nConfiguration has two separate responsibilities:\n\n1. `internal/infrastructure/configuration` loads files, environment variables,\n secret references, overlays, and compatibility representations.\n2. Each domain and plugin owns the typed runtime settings required for its\n behaviour.\n\n`internal/app` translates external input into those settings, validates\ncross-capability combinations, and supplies each component only its own\nsettings.\n\nThe following are prohibited:\n\n- passing complete application configuration into a domain;\n- making a domain depend on TOML, YAML, environment-variable names, secret\n references, or a configuration library;\n- defining a central runtime configuration type imported across the system;\n- placing plugin options in an unrelated global configuration model.\n\n## Private input document\n\n`internal/infrastructure/configuration` MAY use a complete decoded document\nwhile discovering files, decoding sections, and applying overlays. It is an\ninput-boundary DTO only.\n\nThe document:\n\n- remains private to the configuration infrastructure;\n- is composed from separately defined feature sections;\n- is immediately translated by application composition;\n- is never returned as the application's runtime model;\n- is never passed through runtime components.\n\nExternal DTOs and domain runtime settings are separate types.\n\nPlugins supply external configuration definitions through a narrow extension\ncontract. The core loader MUST NOT gain a field or recognized filename for every\nplugin.\n\nInvalid configuration input MUST NOT replace active valid settings or terminate\nunaffected capabilities. Configuration changes use the candidate validation,\npromotion, audit, and recovery requirements in\n[safe-change-and-recovery.md](/dev/architecture/safe-change-and-recovery/).\n\n## Dissolution of `internal/config`\n\n`internal/config` has no target location. It MUST be dissolved and MUST NOT\nsurvive as a shared package, configuration domain, or renamed global model.\n\nIts loading behaviour moves to `internal/infrastructure/configuration`. Existing\ntypes and methods are reassigned by behaviour. Repository execution policy,\ndispatch policy, retry policy, ecosystem defaults, tool policy, memory settings,\nindexing settings, provider settings, and channel settings move to their\nrespective owners.\n\n## Repository settings\n\nThe existing `config.Repo` MUST NOT move intact into a repository domain or\nshared settings package. A managed repository is an application association:\n\n- work intake owns which repository references an identity monitors;\n- task execution owns gates, preflight, test protection, ecosystem behaviour,\n and change limits;\n- task lifecycle owns retry behaviour;\n- scheduling owns concurrency policy;\n- workspace management owns base branch and persistent-storage requirements.\n\nApplication composition correlates these settings by repository reference. No\ndomain receives a universal repository profile.\n\n## Documentation\n\nGenerated configuration reference describes external sections and their owning\ncapabilities. It MUST NOT establish a global Go configuration structure as the\npublic contract.\n\n## Value classification rule\n\nEvery value that controls behaviour MUST have an explicit owner and MUST be\nclassified as exactly one of:\n\n1. **Invariant** — changing it changes the meaning of the program, a wire\n protocol, or a domain concept. It may be a Go constant.\n2. **Runtime setting** — an operator, identity, domain, plugin, or deployment\n may legitimately choose a different value. It is typed configuration owned by\n the affected capability.\n3. **Policy value** — it expresses what is allowed, limited, routed, retried,\n protected, or gated. Its typed definition belongs to the owning domain and it\n is evaluated through the policy system.\n4. **Derived value** — it is computed from other settings and is not\n independently mutable.\n5. **Runtime state** — it changes as the application operates, such as the\n active model for a conversation. It is changed by a domain command and is not\n configuration merely because it can be changed.\n\nAn unclassified behavioural literal is a defect.\n\n`const` MUST NOT be used merely because a value currently has one default.\nConstants are reserved for actual invariants: enum discriminants, protocol\nversions, fixed compatibility tokens, and values whose alteration would change\nthe program's semantics rather than configure an installation.\n\nIn Go, a constant is a compile-time value and does not represent mutable runtime\nstorage. It generally has no address that can be observed or changed.\nArchitecturally, a constant therefore asserts that the value cannot chaLine truncated
"body": "# Configuration\n\n**Status:** Approved; existing-type assignment is ongoing \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Ownership\n\nConfiguration has two separate responsibilities:\n\n1. `internal/infrastructure/configuration` loads files, environment variables,\n secret references, overlays, and compatibility representations.\n2. Each domain and plugin owns the typed runtime settings required for its\n behaviour.\n\n`internal/app` translates external input into those settings, validates\ncross-capability combinations, and supplies each component only its own\nsettings.\n\nThe following are prohibited:\n\n- passing complete application configuration into a domain;\n- making a domain depend on TOML, YAML, environment-variable names, secret\n references, or a configuration library;\n- defining a central runtime configuration type imported across the system;\n- placing plugin options in an unrelated global configuration model.\n\n## Private input document\n\n`internal/infrastructure/configuration` MAY use a complete decoded document\nwhile discovering files, decoding sections, and applying overlays. It is an\ninput-boundary DTO only.\n\nThe document:\n\n- remains private to the configuration infrastructure;\n- is composed from separately defined feature sections;\n- is immediately translated by application composition;\n- is never returned as the application's runtime model;\n- is never passed through runtime components.\n\nExternal DTOs and domain runtime settings are separate types.\n\nPlugins supply external configuration definitions through a narrow extension\ncontract. The core loader MUST NOT gain a field or recognized filename for every\nplugin.\n\nInvalid configuration input MUST NOT replace active valid settings or terminate\nunaffected capabilities. Configuration changes use the candidate validation,\npromotion, audit, and recovery requirements in\n[safe-change-and-recovery.md](/dev/architecture/safe-change-and-recovery/).\n\n## Dissolution of `internal/config`\n\n`internal/config` has no target location. It MUST be dissolved and MUST NOT\nsurvive as a shared package, configuration domain, or renamed global model.\n\nIts loading behaviour moves to `internal/infrastructure/configuration`. Existing\ntypes and methods are reassigned by behaviour. Repository execution policy,\ndispatch policy, retry policy, ecosystem defaults, tool policy, memory settings,\nprovider settings, and channel settings move to their\nrespective owners.\n\n## Repository settings\n\nThe existing `config.Repo` MUST NOT move intact into a repository domain or\nshared settings package. A managed repository is an application association:\n\n- work intake owns which repository references an identity monitors;\n- task execution owns gates, preflight, test protection, ecosystem behaviour,\n and change limits;\n- task lifecycle owns retry behaviour;\n- scheduling owns concurrency policy;\n- workspace management owns base branch and persistent-storage requirements.\n\nApplication composition correlates these settings by repository reference. No\ndomain receives a universal repository profile.\n\n## Documentation\n\nGenerated configuration reference describes external sections and their owning\ncapabilities. It MUST NOT establish a global Go configuration structure as the\npublic contract.\n\n## Value classification rule\n\nEvery value that controls behaviour MUST have an explicit owner and MUST be\nclassified as exactly one of:\n\n1. **Invariant** — changing it changes the meaning of the program, a wire\n protocol, or a domain concept. It may be a Go constant.\n2. **Runtime setting** — an operator, identity, domain, plugin, or deployment\n may legitimately choose a different value. It is typed configuration owned by\n the affected capability.\n3. **Policy value** — it expresses what is allowed, limited, routed, retried,\n protected, or gated. Its typed definition belongs to the owning domain and it\n is evaluated through the policy system.\n4. **Derived value** — it is computed from other settings and is not\n independently mutable.\n5. **Runtime state** — it changes as the application operates, such as the\n active model for a conversation. It is changed by a domain command and is not\n configuration merely because it can be changed.\n\nAn unclassified behavioural literal is a defect.\n\n`const` MUST NOT be used merely because a value currently has one default.\nConstants are reserved for actual invariants: enum discriminants, protocol\nversions, fixed compatibility tokens, and values whose alteration would change\nthe program's semantics rather than configure an installation.\n\nIn Go, a constant is a compile-time value and does not represent mutable runtime\nstorage. It generally has no address that can be observed or changed.\nArchitecturally, a constant therefore asserts that the value cannot change for\nthe lifetiLine truncated
},
{
"url": "/dev/architecture/dashboard-agent-tools/",
@@ -58,13 +58,13 @@
"url": "/dev/architecture/messaging-and-work-intake/",
"title": "Messaging and Work Intake",
"section": "Architecture",
"body": "# Messaging and Work Intake\n\n**Status:** Current state researched; foundation decisions in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie is a personal assistant and general agentic system. Its interactions\ninclude conversation, questions, notes, reminders, goals, message handling,\ntroubleshooting, infrastructure operations, server management, source changes,\nand open-ended future capabilities.\n\nA message to an agent is therefore not inherently a work request, and invoking\nan agent is not inherently a WorkflowExecution.\n\nMessaging and work intake are separate from the Agent System's durable workflow\nexecution model:\n\n- messaging preserves interactions with people and external systems;\n- an agent turn interprets and responds to an interaction using its available\n capabilities;\n- work intake handles the optional promotion of an interaction into durable,\n workflow-backed work;\n- the Agent System owns Workflow definitions and creates WorkflowExecutions.\n\nForge issues, Jira issues, Telegram messages, emails, webhooks, and future\nchannels remain peer external message or artifact sources. None becomes an\nexecution model merely because it can lead to work.\n\n## Confirmed boundary\n\nWork intake MUST NOT create a WorkflowExecution directly.\n\nInbound interactions normally route to the Agent selected by the channel\nbinding. The selected Agent retains its own memory, user knowledge, conversation\ncontinuity, specialisation, and capability context. This continuity is\nindependent of the underlying model or provider.\n\nEach selected Agent acts through its own immutable IdentityID. Interaction and\nresulting action records preserve both that acting identity and the initiating\nuser identity when one exists.\n\nAgent memory is private by default. Interaction context MAY additionally use\nuser-wide memory and intentionally global shared memory, but another Agent's\nagent-wide memory is not part of the selected Agent's context.\n\nMultiple users may interact with the same Agent. The channel binding and inbound\nmessage MUST resolve both AgentID and initiating User IdentityID before\nconversation or memory context is loaded. Sharing an Agent MUST NOT implicitly\nshare one user's private memory with another user.\n\nAn interaction may assemble memory from four scopes: global shared, the selected\nAgent's agent-wide memory, the initiating user's authorized user-wide memory,\nand the private Agent-user relationship memory addressed by both IDs.\n\n## Conversation identity\n\nEvery conversation is identified by the complete tuple:\n\n```text\nAgentID\n+ UserIdentityID\n+ ChannelBindingID\n+ ExternalConversationID\n+ ThreadID\n```\n\n`ThreadID` has an explicit empty value for channels without threads. No element\nof this key may be replaced by a display name, configured bot username, channel\ntype, or other mutable label.\n\nAgent and user memory continue across conversations according to their memory\nscope. Immediate conversation history and delivery correlation remain isolated\nto the identified channel conversation or thread. Moving between Telegram,\nemail, or another channel does not create a new Agent or user, but it does\ncreate a distinct conversation unless an explicit linking operation relates\nthem.\n\nConversation and message events support projections for channel-entry metrics,\nuse cases, volumes, outcomes, latency, capability usage, and other product or\noperational analysis. Metrics are derived read models; they MUST NOT become\nmutable counters embedded in the conversation aggregate or change message\nrouting semantics.\n\n## Canonical messages\n\nEvery inbound, assistant, tool-call, and tool-result message has an immutable\napplication-generated MessageID. Platform identifiers are external correlation,\nnot substitutes for the canonical ID.\n\nMessages are addressable because an interaction is more than text. A message may\ncontain assistant content, reasoning data subject to its retention policy, one\nor more tool calls, a tool result with authoritative execution metadata,\nattachments, reply relationships, edits, or other typed content. Stable\nMessageIDs also allow sessions to branch from an exact prior point.\n\nThe canonical session and message implementation must supply:\n\n- application-generated stable message IDs;\n- user, assistant, and tool roles;\n- assistant tool calls and correlated tool-result messages;\n- authoritative tool-result status, timing, error, truncation, and size\n metadata;\n- session lifecycle and active-request state;\n- session-to-agent-instance and parent-session lineage;\n- durable SQLite round trips and timestamp validation.\n\nThese semantics must use the confirmed Agent, user, channel-binding, and\nconversation ownership model.\n\nThe canonical message store MUST preserve messages as immutable records and\nrepresent later edits, deletions,Line truncated
"body": "# Messaging and Work Intake\n\n**Status:** Current state researched; foundation decisions in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie is a personal assistant and general agentic system. Its interactions\ninclude conversation, questions, notes, reminders, goals, message handling,\ntroubleshooting, infrastructure operations, server management, source changes,\nand open-ended future capabilities.\n\nA message to an agent is therefore not inherently a work request, and invoking\nan agent is not inherently a WorkflowExecution.\n\nMessaging and work intake are separate from the Agent System's durable workflow\nexecution model:\n\n- messaging preserves interactions with people and external systems;\n- an agent turn interprets and responds to an interaction using its available\n capabilities;\n- work intake handles the optional promotion of an interaction into durable,\n workflow-backed work;\n- the Agent System owns Workflow definitions and creates WorkflowExecutions.\n\nForge issues, Jira issues, Telegram messages, emails, webhooks, and future\nchannels remain peer external message or artifact sources. None becomes an\nexecution model merely because it can lead to work.\n\n## Confirmed boundary\n\nWork intake MUST NOT create a WorkflowExecution directly.\n\nInbound interactions normally route to the Agent selected by the channel\nbinding. The selected Agent retains its own memory, user knowledge, conversation\ncontinuity, specialisation, and capability context. This continuity is\nindependent of the underlying model or provider.\n\nEach selected Agent acts through its own immutable IdentityID. Interaction and\nresulting action records preserve both that acting identity and the initiating\nuser identity when one exists.\n\nAgent memory is private by default. Interaction context MAY additionally use\nuser-wide memory and intentionally global shared memory, but another Agent's\nagent-wide memory is not part of the selected Agent's context.\n\nMultiple users may interact with the same Agent. The channel binding and inbound\nmessage MUST resolve both AgentID and initiating User IdentityID before\nconversation or memory context is loaded. Sharing an Agent MUST NOT implicitly\nshare one user's private memory with another user.\n\nAn interaction may assemble memory from four scopes: global shared, the selected\nAgent's agent-wide memory, the initiating user's authorized user-wide memory,\nand the private Agent-user relationship memory addressed by both IDs.\n\n## Conversation identity\n\nEvery conversation is identified by the complete tuple:\n\n```text\nAgentID\n+ UserIdentityID\n+ ChannelBindingID\n+ ExternalConversationID\n+ ThreadID\n```\n\n`ThreadID` has an explicit empty value for channels without threads. No element\nof this key may be replaced by a display name, configured bot username, channel\ntype, or other mutable label.\n\nAgent and user memory continue across conversations according to their memory\nscope. Immediate conversation history and delivery correlation remain isolated\nto the identified channel conversation or thread. Moving between Telegram,\nemail, or another channel does not create a new Agent or user, but it does\ncreate a distinct conversation unless an explicit linking operation relates\nthem.\n\nConversation and message events support projections for channel-entry metrics,\nuse cases, volumes, outcomes, latency, capability usage, and other product or\noperational analysis. Metrics are derived read models; they MUST NOT become\nmutable counters embedded in the conversation aggregate or change message\nrouting semantics.\n\n## Canonical messages\n\nEvery inbound, assistant, tool-call, and tool-result message has an immutable\napplication-generated MessageID. Platform identifiers are external correlation,\nnot substitutes for the canonical ID.\n\nMessages are addressable because an interaction is more than text. A message may\ncontain assistant content, reasoning data subject to its retention policy, one\nor more tool calls, a tool result with authoritative execution metadata,\nattachments, reply relationships, edits, or other typed content. Stable\nMessageIDs also allow sessions to branch from an exact prior point.\n\nThe canonical session and message implementation must supply:\n\n- application-generated stable message IDs;\n- user, assistant, and tool roles;\n- assistant tool calls and correlated tool-result messages;\n- authoritative tool-result status, timing, error, truncation, and size\n metadata;\n- session lifecycle and active-request state;\n- session-to-agent-instance and parent-session lineage;\n- durable SQLite round trips and timestamp validation.\n\nThese semantics must use the confirmed Agent, user, channel-binding, and\nconversation ownership model.\n\nThe canonical message store MUST preserve messages as immutable records and\nrepresent later edits, deletions,Line truncated
},
{
"url": "/dev/architecture/migration-decisions/",
"title": "Architecture Migration Decisions",
"section": "Architecture",
"body": "# Architecture Migration Decisions\n\n**Status:** Active migration inventory \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nThis document records what remains to be decided before Archie's current\nimplementation can be migrated into the approved domain-oriented structure.\n\nThe product and core domain model are not being redesigned. Existing Archie\nbehaviour and the existing session implementation are the migration\nbaseline. Remaining decisions MUST be grounded in current packages, consumers,\ntests, persistence, and runtime wiring.\n\n## Confirmed domain packages\n\n```text\ninternal/domain/\n identity/ (approved, not yet materialised as a package)\n agent/ (approved, not yet materialised as a package)\n workflow/\n messaging/ (canonical Message/Conversation types only; gateway migration pending, see section 2)\n workintake/\n plugin/ (approved, not yet materialised as a package)\n curator/\n mapping/\n scheduling/\n```\n\n- `identity` owns persistent actors, lifecycle, ownership, attribution, and\n audit identity.\n- `agent` owns persistent assistants, specialisation, instructions,\n model-independent continuity, capability context, and associations with\n identity and memory.\n- `workflow` is a separate domain. It owns reusable, versioned Workflow\n definitions, WorkflowSteps, WorkflowExecutions, StepExecutions, Attempts,\n outcomes, and typed Workflow plugin contracts.\n- `messaging` owns canonical Messages, Conversations, branches, channel and\n source correlation, replies, acknowledgements, delivery attempts, events, and\n projections.\n- `workintake` owns admission, validation, deterministic routing, and accepted\n work requests for the optional transition into durable workflow-backed\n execution.\n- `plugin` owns generic plugin identity, discovery, compatibility, and lifecycle\n mechanics. It remains metadata-only; capability semantics and typed\n registration belong to the owning domain.\n- `curator` owns the curator engine family: long-running agent loops that\n reason over memory and perform maintenance tasks on a declared shape\n (check-in interval, tool set, attached memory engine). See epic\n archie-core-yp9.\n- `mapping` owns the payload field-mapping vocabulary: binding named fields to\n JSON paths inside a captured webhook payload, and detecting drift. See\n `docs/prds/payload-field-mapping.md`.\n- `scheduling` owns the ticker engine: deciding when a scheduled job runs and\n with what concurrency. It declares `JobSource`/`Runner` contracts and owns\n no storage or delivery. See epic archie-core-1786637496320-249-be6d9a20.\n\n**Reconciliation (2026-08-31):** `curator`, `mapping`, and `scheduling` existed\nin the tree without being added to this list when their epics landed. They are\nconfirmed as legitimate, narrowly-scoped domains under the same rules as the\noriginal six — each owns one capability family, declares typed contracts, and\nhas no cross-domain reach. This list was out of date, not the tree.\n\nConversely, `identity`, `agent`, `messaging`, and `plugin` are approved target\ndomains that do not yet exist as packages. Their behaviour currently lives in\npre-migration packages (see \"Complete package destination map\" below for the\nfull inventory). Do **not** create empty stub packages for them ahead of an\nactual migration PR — an unused stub is dead code and gives no test coverage.\nEach materialises when its corresponding migration decision below is resolved\nand implemented in the same change.\n\nMemory's final package placement remains undecided pending focused review of the\nexisting implementation.\n\nThe following are approved shared or composition packages, not domains:\n\n```text\ninternal/eventbus/\ninternal/policy/\ninternal/infrastructure/\ninternal/app/archied/\ninternal/app/agentworker/\n```\n\n## Remaining migration decisions\n\n### 1. Complete package destination map\n\nEvery current package MUST receive one explicit disposition:\n\n- move into a confirmed domain;\n- move under infrastructure as an implementation of a domain-owned contract;\n- move into application composition;\n- merge with an identified duplicate;\n- remain as an approved shared application contract;\n- move to a plugin, extra, deployment, example, or generated artifact;\n- be deleted after its replacement is proven.\n\nThe largest unreviewed areas include memory, tools and capabilities, workspace\nand worktree behaviour, gates, storage, events, web UI, containers, RPC\npackages, release management, and scheduling.\n\nThe destination matrix MUST name the behaviour owner, target path, dependencies\nto remove, state and contracts to preserve, migration prerequisites, and\ndeletion criteria.\n\n**`internal/webui` / UI Service — RATIFIED Phase 3 disposition (2026-09-07).**\nThe current owner is the in-process HTTP/SSE dashboard: SPA hosting, operator\nauthLine truncated
"body": "# Architecture Migration Decisions\n\n**Status:** Active migration inventory \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nThis document records what remains to be decided before Archie's current\nimplementation can be migrated into the approved domain-oriented structure.\n\nThe product and core domain model are not being redesigned. Existing Archie\nbehaviour and the existing session implementation are the migration\nbaseline. Remaining decisions MUST be grounded in current packages, consumers,\ntests, persistence, and runtime wiring.\n\n## Confirmed domain packages\n\n```text\ninternal/domain/\n identity/ (approved, not yet materialised as a package)\n agent/ (approved, not yet materialised as a package)\n workflow/\n messaging/ (canonical Message/Conversation types only; gateway migration pending, see section 2)\n workintake/\n plugin/ (approved, not yet materialised as a package)\n curator/\n mapping/\n scheduling/\n```\n\n- `identity` owns persistent actors, lifecycle, ownership, attribution, and\n audit identity.\n- `agent` owns persistent assistants, specialisation, instructions,\n model-independent continuity, capability context, and associations with\n identity and memory.\n- `workflow` is a separate domain. It owns reusable, versioned Workflow\n definitions, WorkflowSteps, WorkflowExecutions, StepExecutions, Attempts,\n outcomes, and typed Workflow plugin contracts.\n- `messaging` owns canonical Messages, Conversations, branches, channel and\n source correlation, replies, acknowledgements, delivery attempts, events, and\n projections.\n- `workintake` owns admission, validation, deterministic routing, and accepted\n work requests for the optional transition into durable workflow-backed\n execution.\n- `plugin` owns generic plugin identity, discovery, compatibility, and lifecycle\n mechanics. It remains metadata-only; capability semantics and typed\n registration belong to the owning domain.\n- `curator` owns the curator engine family: long-running agent loops that\n reason over memory and perform maintenance tasks on a declared shape\n (check-in interval, tool set, attached memory engine). See epic\n archie-core-yp9.\n- `mapping` owns the payload field-mapping vocabulary: binding named fields to\n JSON paths inside a captured webhook payload, and detecting drift. See\n `docs/prds/payload-field-mapping.md`.\n- `scheduling` owns the ticker engine: deciding when a scheduled job runs and\n with what concurrency. It declares `JobSource`/`Runner` contracts and owns\n no storage or delivery. See epic archie-core-1786637496320-249-be6d9a20.\n\n**Reconciliation (2026-08-31):** `curator`, `mapping`, and `scheduling` existed\nin the tree without being added to this list when their epics landed. They are\nconfirmed as legitimate, narrowly-scoped domains under the same rules as the\noriginal six — each owns one capability family, declares typed contracts, and\nhas no cross-domain reach. This list was out of date, not the tree.\n\nConversely, `identity`, `agent`, `messaging`, and `plugin` are approved target\ndomains that do not yet exist as packages. Their behaviour currently lives in\npre-migration packages (see \"Complete package destination map\" below for the\nfull inventory). Do **not** create empty stub packages for them ahead of an\nactual migration PR — an unused stub is dead code and gives no test coverage.\nEach materialises when its corresponding migration decision below is resolved\nand implemented in the same change.\n\nMemory's final package placement remains undecided pending focused review of the\nexisting implementation.\n\nThe following are approved shared or composition packages, not domains:\n\n```text\ninternal/eventbus/\ninternal/policy/\ninternal/infrastructure/\ninternal/app/archied/\ninternal/app/agentworker/\n```\n\n## Remaining migration decisions\n\n### 1. Complete package destination map\n\nEvery current package MUST receive one explicit disposition:\n\n- move into a confirmed domain;\n- move under infrastructure as an implementation of a domain-owned contract;\n- move into application composition;\n- merge with an identified duplicate;\n- remain as an approved shared application contract;\n- move to a plugin, extra, deployment, example, or generated artifact;\n- be deleted after its replacement is proven.\n\nThe largest unreviewed areas include memory, tools and capabilities, workspace\nand worktree behaviour, gates, storage, events, web UI, containers, RPC\npackages, release management, and scheduling.\n\nThe destination matrix MUST name the behaviour owner, target path, dependencies\nto remove, state and contracts to preserve, migration prerequisites, and\ndeletion criteria.\n\n**`internal/webui` / UI Service — RATIFIED Phase 3 disposition (2026-09-07).**\nThe current owner is the in-process HTTP/SSE dashboard: SPA hosting, operator\nauthLine truncated
},
{
"url": "/dev/architecture/observability/",
@@ -88,7 +88,7 @@
"url": "/dev/architecture/plugins-and-extensions/",
"title": "Plugins and Extensions",
"section": "Architecture",
"body": "# Plugins and Extensions\n\n**Status:** Approved foundation \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Plugin framework\n\nThe core plugin domain lives under `internal/domain/plugin`. It owns:\n\n- plugin identity and metadata;\n- discovery and registration contracts;\n- lifecycle rules;\n- capability registration;\n- validation and compatibility rules.\n\nThe generic plugin contract remains metadata-only. Functionality is exposed\nthrough narrow typed capability contracts with an owning registry or manager.\n\nWorkflow plugins belong to the Workflow capability family. The Workflow domain\nat `internal/domain/workflow` owns their typed registration, validation,\nversioning, definition, and execution contracts. The generic plugin domain may\nprovide plugin identity, discovery, compatibility, and lifecycle mechanics, but\nit MUST NOT define Workflow semantics or expose untyped Workflow hooks.\n\n## Plugin implementations\n\nFirst-party plugins are self-contained vertical modules under\n`plugins/\u003cplugin\u003e`.\n\nA plugin:\n\n- owns its implementation, settings, templates, assets, and tests;\n- receives only explicitly supplied contracts and services;\n- MUST NOT receive daemon internals, a service locator, or unrestricted\n application access;\n- MUST NOT import arbitrary infrastructure or application composition code;\n- MAY use approved domain and shared application contracts;\n- MUST remain removable without changes to unrelated domains.\n\nPlugins may be internally cohesive like small services. They do not become\nnetwork services without a concrete security or operational reason.\n\n## Event sources and reactions\n\n`archie-core-7d5u.1` asked whether extensions should react to events\nin-process through typed capability families (this document's model) or\nout-of-process like a generic `DispatchEvent` dispatcher. Decided 2026-08-22\nin `docs/prds/event-sources-and-reactions.md`: in-process typed families,\nconfirming this document's model rather than amending it. The forge webhook\nreceiver (`internal/forge/webhook`, see `ARCHITECTURE.md`'s \"Webhook intake\"\nsection) and the EDA playbook engine's Module action position\n(`docs/prds/eda-playbook-engine.md`, `internal/domain/eda/module`) are the\nshipped instances of that decision -- each is a narrow typed contract with an\nowning registry, not a generic event hook. The playbook engine's Channel and\nForge action positions are designed but not yet implemented (open\ninvestigation `archie-core-t2db.19`); when they land they follow the same\nmodel, not a new one.\n\n## Curator surprisal sampling\n\n**Decided 2026-08-05, wave 1 landed 2026-09-05** — the curator engine family\n(epic [#435](https://github.com/samcharles93/archie-core/issues/435)) selects which memories deserve agentic attention via\nsurprisal-based sampling: score memories by how surprising they are and\nspend the sampled reasoner's agentic budget on the most surprising items.\n\nThe prerequisites are built: the embeddings capability\n([#436](https://github.com/samcharles93/archie-core/issues/436), `internal/domain/embedding` contract +\n`internal/infrastructure/embedding` implementation, config-driven via\n`models.embedding`) and the wave-1 `Sampler` strategy seam\n(`internal/domain/sampling` -- not `internal/curator`, see\n`docs/prds/curator-sampler-wave1.md` for the settled design and tracking)\nwith four\ncheap, embedding-free strategies (recency, random, all, staleness proxy).\nNo curator consumes a `Sampler` yet, and the embeddings client is likewise\ndeliberately inert: `setupEmbeddings` constructs it at boot and holds it on\n`b.embeddings`, but no production code reads that field yet, so a resolved\n`models.embedding` role currently produces a client whose only observable\neffect is a boot log line. Both are prerequisites waiting on #437, not\nunwired defects.\n\nStill deferred: [#437](https://github.com/samcharles93/archie-core/issues/437), the embedding-backed surprisal strategy, which\ndepends on the above and on [#407](https://github.com/samcharles93/archie-core/issues/407). Requirements for that deferred work,\nso it can be picked up without re-deriving the design:\n\n- A `Sampler` implementation behind the same interface as the cheap\n strategies; selection deterministic given fixed inputs.\n- Algorithm: sample up to a candidate cap; build a k-NN graph over embedding\n vectors; row-normalize the adjacency with self-loops; power-iterate to the\n stationary distribution; surprisal = −log(stationary probability of the\n nearest point); select the highest-surprisal items.\n- Degradation: content without an embedding is skipped; an embedding failure\n aborts sampling and falls back to free exploration — a sampling failure\n must never fail or crash a curator pass.\n- Cost bound: the graph build is quadratic in the candidate cap; the cap must\n be a named constant with a documentLine truncated
"body": "# Plugins and Extensions\n\n**Status:** Approved foundation \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Plugin framework\n\nThe core plugin domain lives under `internal/domain/plugin`. It owns:\n\n- plugin identity and metadata;\n- discovery and registration contracts;\n- lifecycle rules;\n- capability registration;\n- validation and compatibility rules.\n\nThe generic plugin contract remains metadata-only. Functionality is exposed\nthrough narrow typed capability contracts with an owning registry or manager.\n\nWorkflow plugins belong to the Workflow capability family. The Workflow domain\nat `internal/domain/workflow` owns their typed registration, validation,\nversioning, definition, and execution contracts. The generic plugin domain may\nprovide plugin identity, discovery, compatibility, and lifecycle mechanics, but\nit MUST NOT define Workflow semantics or expose untyped Workflow hooks.\n\n## Plugin engine rule (strict)\n\n“Engine” is reserved for a typed, lifecycle-managed capability family. It is not\na synonym for a generic plugin hook. Every new plugin engine must satisfy all of\nthese invariants:\n\n1. **Typed domain contract.** The engine interface exposes real\n capability-specific operations in addition to identity metadata. Examples are\n resolving a secret, delivering a message, or running an agent. A plugin that\n only exposes `Name` and `Version` is metadata, not an engine.\n2. **Owning family manager.** The capability package owns a `Registry` or\n `Manager` that controls provider registration and discovery, initialization,\n or access. Providers do not register arbitrary callbacks directly on the\n daemon.\n3. **Lifecycle and health.** When an implementation owns resources or background\n work, its typed family contract must expose start, health, and stop\n semantics. The owning manager invokes them and defines failure isolation and\n shutdown ordering. Stateless providers may make these operations explicit\n no-ops.\n4. **Narrow host access.** Plugins receive the typed family registrar and only\n the host services their declared capability requires. They never receive\n `*daemon.Daemon`, a service locator, or an untyped hook map.\n5. **Metadata-only generic plugin contract.** `plugin.Plugin` remains limited to\n `Name()` and `Version()`. Domain hooks belong on typed engine interfaces;\n adding capability methods to the generic interface is forbidden.\n6. **Trust boundary stays explicit.** Explicitly trusted, operator-installed\n plugins—including third-party secret-engine plugins the operator chooses to\n trust—may run in-process and have daemon privileges. Repository-supplied code\n runs in the task container. Integrations that are not trusted as daemon code\n run out of process through MCP or a versioned protocol and, when a\n confidentiality or integrity boundary is required, inside a real container\n sandbox. A subprocess boundary alone is not a security sandbox, and calling\n Yaegi-loaded code a plugin does not isolate it.\n\n`internal/plugin/architecture_test.go` enforces the mechanically testable parts\nof this rule: the generic plugin method set, the shared agent-instruction\nsource, and the requirement that engine interfaces have domain behavior plus an\nowning registry or manager.\n\n### Memory engine family\n\nOne engine, addressed by four typed scopes -- `ScopeGlobal`, `ScopeAgent`,\n`ScopeUser`, `ScopeAgentUser` (`internal/domain/memory`, `Scope`/`ScopeKind`).\nA caller names exactly the scopes it may read or write; the engine applies no\naccess policy of its own, so isolation falls out mechanically because\n`ScopeAgent{a}` and `ScopeAgent{b}` are different storage keys. See\n`docs/prds/memory-engine-unification.md` for the decision this contract\nimplements; it superseded `internal/memory` (`MemoryProvider`/`Manager`),\ndeleted in that PRD's slice 5.\n\n`MemoryEngine` (`internal/domain/memory/contract.go`) is the typed family\ncontract: `Create`, `Get`, `Query`, `List`, `Update`, `Forget`, `Revisions` --\nCRUD with revisions retained, not just create/read/delete. `Update` supersedes\nrather than overwrites: the superseded state is appended to the scope's\n`HISTORY.md` before the live block is replaced, and `Update` carries no\n`Scope` field, so a record can never change scope. The family's content\nscanner (prompt-injection / sensitive-data patterns) is applied inside\n`Create` and `Update`, the single choke point every producer crosses.\n\n`internal/domain/memory.Registry` is the owning family registry: registration,\nstart/health/stop, shutdown ordering, and failure isolation, following the\nplugin engine rule above. `internal/infrastructure/memory.NewBuiltinEngine` is\nthe only registered engine today; it persists through\n`internal/infrastructure/memory/builtin`, a markdown store (`MEMORY.md`-shaped\nper-scope files) that owns its on-diLine truncated
},
{
"url": "/dev/architecture/policy/",
@@ -126,6 +126,12 @@
"section": "PRDs",
"body": "# Agent2Agent as archie's agent-to-agent protocol — decision\n\n**Status:** Draft\n**Date:** 2026-09-22\n**Authority:** the A2A Protocol Specification v1.0.0 (`a2a-protocol.org`) for the\nprotocol, `docs/architecture/organisation.md` for package placement, and\n`docs/architecture/migration-decisions.md` §2 for session and messaging design.\n\n## Decision\n\nA2A is the protocol archie speaks to other agents. It carries agent-to-agent\nwork: discovery of what a remote agent offers, delegation of a unit of work to it,\nprogress on that work, and the artifacts it produces.\n\n## Layers\n\n**MCP stays the tool layer.** MCP connects a model to tools and data; A2A connects\nagents to agents. They are complementary and archie runs both:\n`internal/tools/provider` registers MCP providers as optional capabilities, so an\nA2A call and an MCP tool call are different kinds of traffic with different\nowners.\n\n**A2A rides archie's existing transports.** A2A's canonical data model is\nProtocol Buffer messages and it defines a gRPC binding, so archie speaks A2A over\nthe gRPC and NATS it already runs. A second wire format, a second broker, or a\nbespoke protocol for agent-to-agent traffic is a requirement not to introduce.\n\n## Where A2A stops\n\nA2A is not a general replacement for either of the two protocols archie already\nhas, and each boundary is a requirement rather than a preference.\n\n- **`internal/domain/messaging` stays the human and channel layer.** A\n Conversation is a ChannelID and a ThreadID, its participants are people on\n Telegram, email, webhook and the dashboard, and its records are what a curator\n reads. An A2A peer is not a channel participant and does not address a\n Conversation.\n- **`internal/agentexec` stays the daemon-to-worker execution protocol.** It\n carries a Request, a Result, gate and budget policy, and capture tools between\n the daemon and the agent container it owns. An A2A peer never receives that\n protocol, and A2A never carries gate, budget or protection policy.\n\nA2A is therefore an edge protocol: it exchanges work with peers outside archie's\nown process boundary, and it composes with the two protocols above rather than\nreplacing or abstracting them.\n\n## A2A Task mapping\n\n**Decision: archie's work lifecycle is mapped to A2A's, not expressed in it. An\nA2A Task is a view over archie's own task, and archie's status remains the record\nof truth.**\n\nThis is the load-bearing decision, because A2A's Task carries its own state\nmachine and archie's lifecycle is the on-disk format of its task store, whose\nstatus strings a rename migrates rather than changes.\n\nThe mapping is partial, and each gap is a case where archie knows something A2A's\nstates do not carry:\n\n- **Completion by another system.** A2A's terminal states describe what the agent\n did (`completed`, `failed`, `canceled`, `rejected`). archie's `merged` and\n `rejected` describe what a forge did to a pull request after archie finished\n its work. There is no A2A state for \"an external system accepted this\", so a\n completed A2A task cannot express the outcome that matters most to the caller.\n- **Handing work to a reviewer.** archie's `pr_open` means the work left\n archie's hands for human review. A2A's `input-required` is the nearest state,\n but it means the *client* must send more input, and a reviewer is not the\n client.\n- **Operator decisions.** `declined`, `parked` and `dead` are outcomes of\n archie's own policy and operator actions. A2A has no state for \"the operator\n refused this\" or \"a budget ran out and an operator must decide\".\n\nA WorkflowExecution is the unit an A2A task maps onto, because it is the attempt\nthat runs, streams and produces artifacts, and a follow-up attempt is a new\nexecution. A2A's own model agrees that a task is immutable once terminal and that\na refinement is a new task sharing the `contextId`, which is why archie's\nper-attempt executions and A2A's per-request tasks correspond.\n\n**Requirement:** the A2A state a peer sees is derived from archie's status by one\nmapping, and archie's status is carried on the task so a peer can read what the\nderivation lost. The mapping is total in the direction that matters -- every\narchie status has an A2A state -- and deliberately not injective, because the\ngaps above are facts A2A cannot hold.\n\n**Requirement:** adopting A2A's state names as archie's persisted task status is\nrejected. It would migrate the task store, and it would drop the forge outcomes\nthat tell a caller whether the work was accepted.\n\n## What an A2A agent is\n\n**An A2A agent is an archie Identity.** The Agent Card describes a durable,\naddressable actor with an endpoint, capabilities and authentication requirements,\nand an Identity is the actor archie persists, versions, suspends and scopes\ncredentials to.\n\nAn `agent.Persona` is not an A2A agent: a persona is prompt text selected for a\nturn, and it has no endpLine truncated
},
{
"url": "/dev/prds/artifact-sender/",
"title": "Artifact sender",
"section": "PRDs",
"body": "# Artifact sender\n\n**Status:** Approved\n**Revision:** 1\n**Authority:** this document\n\n## Purpose\n\narchie-core publishes artifacts — design documents, review reports, research briefs,\nrunnable pages — to the offloaded.dev collaborative editor. A person reads the\nartifact, comments on it, and the artifact page is the shared surface for iteration.\n\nThe receiving contract is owned by the editor: `POST /api/artifacts` with a bearer\nservice token, a closed field set, and server-side idempotency on `requestId` plus\nlast-write-wins on `sentAt`. This document owns only what archie-core sends.\n\n## Scope\n\nVersion one publishes one-way: archie-core sends, the editor receives. The first\nproducer is the pull-request adversarial review: a completed `ReviewReport` is\nrendered to markdown and published after the review completes.\n\nChat-surface tools (`create_artifact`, `update_artifact`), comment read-back, share\ntokens, and runnable-format producers (`html`, `react`, `vue`) are later slices. The\nreceiving contract already carries them; version one does not exercise them.\n\n## Configuration\n\n- New `[artifacts]` section: `base_url` (site origin), `token` (`SecretRef`) with\n `token_env` fallback naming `WORKSPACE_INGEST_TOKEN`.\n- An empty `base_url` disables the sender: no client is constructed, nothing is\n registered, and publishing degrades to a log line.\n- The token is runtime configuration. It is never baked at build time.\n\n## Sender\n\n- New package `internal/infrastructure/artifactsync` exposing one method,\n `Publish(ctx, Artifact) (string, error)`, where the string is the artifact URL.\n One-method injected seam, concrete client constructed by the boot path when the\n configuration resolves — the `crondelivery.Courier` posture.\n- The client POSTs the frozen contract body. Each publish sends the complete\n source: versions of record are full snapshots, never diffs.\n- A `503` response is retried three times with backoff. `401` and `400` are not\n retried; they are logged with the field reason the response names.\n- `requestId` is `artifact:\u003ctask-id\u003e:\u003cversion\u003e` when the producer is task-backed,\n otherwise `artifact:\u003cidentity\u003e:\u003csentAt-utc\u003e`. Sending the same `requestId` with\n an equal or older `sentAt` must be a server-side no-op, which makes sender-side\n retry safe.\n\n## Report rendering\n\n- `ReviewReport` gains a pure markdown renderer in `internal/domain/workflow`:\n the summary as the lede, one finding per subsection with file, line, verdict,\n level and the failure scenario, and the verified properties as a \"checked\n clean\" list. Findings carry their disposition when present.\n- The renderer performs no I/O and imports no infrastructure.\n\n## Attribution\n\n- `actor`: the producing identity. The reviewer publishes as `system:pr-reviewer`\n when no task identity resolves; otherwise the task's identity name.\n- `source`: the producing subsystem, `pr-review` for version one.\n- `task`: owner, repository and issue number from the task when one exists.\n\n## Failure behaviour\n\n- Publishing never fails the producing work. A failed publish is logged with its\n status and reason; the artifact is republished on the next production of the\n same artifact.\n- A successful publish records the artifact URL in the run report, so the PR\n description or task log links to the readable artifact.\n- The published URL is the editor deep link for the artifact, keyed on its\n immutable id. archie-core never mints share links; sharing is an\n account-holder decision made in the editor.\n\n## Verification\n\n- Client tests against a test server cover 201, 401, 400 with a field reason,\n and 503 retry behaviour.\n- The report renderer test covers a report with findings, checks, dispositions\n and a not-run status.\n- Configuration tests cover the disabled case, the `SecretRef` path and the\n `token_env` fallback."
},
{
"url": "/dev/prds/binding-secret-encryption/",
"title": "Binding secret at-rest encryption -- decision",
@@ -202,7 +208,7 @@
"url": "/dev/prds/deep-research-capability/",
"title": "Deep research capability — design",
"section": "PRDs",
"body": "# Deep research capability — design\n\n**Status:** Draft\n**Date:** 2026-09-14\n**Scope:** A deep-research capability in archie-core: an orchestrator that\nspawns 1..N subagents to explore and research in parallel, collates their\nfindings, and returns one cited report. Grounded in web search and web fetch.\n**Beads issue:** none yet (this document is the input to it)\n**Depends on:** nothing shipped for slice 1; slice 2 depends on slice 1.\n\n## §0 Implementation status\n\nEvery claim in this document is mapped to what exists in the tree.\n\n| Claim | Status | Where it stands |\n|---|---|---|\n| `web_fetch` tool (URL → readable text) | **Implemented** | `internal/tools/webfetch/{tool.go,webfetch.go}`; registered in `internal/app/archied/bootstrap.go` `registerStandaloneTools`, disabled-by-config returns `nil` |\n| **Web search** (query → result list) | **Aspirational — zero code** | No search provider, no search tool, no config block anywhere in the tree or in `ai-sdk` v0.1.32 |\n| `agent.Subagent` — nested agent in a fresh context window | **Implemented** (dependency) | `github.com/samcharles93/ai-sdk@v0.1.32/agent/subagent.go`. Synchronous, non-streaming, own model/system/toolset, `MaxSteps` defaults to 10, nesting depth capped at 5, returns final text only |\n| Subagent used in production | **Implemented, one consumer** | `internal/app/agentworker/review.go` — the adversarial reviewer. That is the only non-test use of `Subagent` in the repo |\n| A **delegate/subagent tool** on the chat surface | **Aspirational — zero code** | No `subagent`/`delegate` tool name is registered anywhere |\n| **Fan-out orchestration** (N missions, one collator) | **Aspirational — zero code** | `agentloop`'s package doc states it runs *one* mission: \"orchestration across missions lives with the caller\". No caller does this yet |\n| Parallel-safe tool execution | **Aspirational — zero code** | The unreachable `internal/tools/dispatch.go` dispatch/gating engine (`ExecutionClass`, `DispatchSequential`/`DispatchConcurrent`/`ClassifyEntry`) was deleted as dead code (tools-core-1); live concurrency is ai-sdk's `GenerateOptions.MaxParallelToolCalls`, which archie-core never sets |\n| Per-result caps + spill-to-disk | **Implemented** | `internal/agentexec/toolset.go` `ToolLimits{MaxResultChars,SpillDir}`, applied in `toolExecute` via `tools.CapPayload` (`limit.go`); no **aggregate** turn cap by design (`toolset.go`). `config.ToolPolicy.SpillDir`; default cap 50k chars, spill dir deliberately not defaulted |\n| Tool guardrails (repeat-failure / no-progress) | **Implemented, not on the call path** | `internal/tools/guardrail.go` engine exists. Its only non-test caller is `dispatchOne` — which is itself unreachable — so **the chat path never consults it**, and the agent path only records per *stage* (`domain/workflow/agent.go`) |\n| Structured capture tools (model reports into a typed store, not prose) | **Implemented** | `internal/app/agentworker/review.go` `record_finding` / `record_checked` — `core.NewTypedTool` appending to a caller-owned slice. This is the pattern a research source ledger should reuse |\n| Curator engine (interval, declared tool set, lifecycle) | **Implemented, tools broken** | `internal/domain/curator`; a curator declaring tools is **refused** at registration (`registry.go`, no `ToolBuilder` implementation) and `curatorLLMRunner` (`internal/app/archied/main.go`) drops `ChatRequest.Tools`. Budgets are time+concurrency only (`runtime.go`) — **no token budget** |\n| Cron / scheduling + delivery router | **Implemented, wired into no binary** | `internal/domain/scheduling`, `internal/infrastructure/cronstore` (schema v2, `Kind` discriminator), `internal/infrastructure/crondelivery` — all present and green, but `go list -deps` for every `cmd/` contains none of them, and `cron`-expression firing arithmetic is unimplemented (`schedule.go`, \"slice 2\"). `ARCHITECTURE.md` still asserts \"**No daemon-internal cron.**\" |\n| Workflow engines (multi-stage, resumable) | **Implemented, worktree-bound** | `internal/domain/workflow` — every non-triage workflow opens with `StagePrepareWorktree()` and mounts `tc.Dir` into a container; the task persists after every stage (`workflow.go`). `triage.go` documents there is \"no cheaper directory-less classification primitive\" |\n| Long-running chat-initiated work with progress | **Partial** | Chat turns run **once, synchronously**, inline in the channel's turn runner (`internal/gateway/turn.go`). Chat can spawn a *workflow task* (`task_spawn`) which is asynchronous — but that path is worktree/PR-shaped |\n| **Operator-push delivery of an async result** | **Aspirational — zero code** | Nothing pushes a finished result to a chat. No channel subscribes to the event bus (Telegram only *publishes* `KindTurnCompleted`); `crondelivery.Courier` is the intended seam but has **no implementation and no caller**; `send_file` works only inside theLine truncated
"body": "# Deep research capability — design\n\n**Status:** Draft\n**Date:** 2026-09-14\n**Scope:** A deep-research capability in archie-core: an orchestrator that\nspawns 1..N subagents to explore and research in parallel, collates their\nfindings, and returns one cited report. Grounded in web search and web fetch.\n**Beads issue:** none yet (this document is the input to it)\n**Depends on:** nothing shipped for slice 1; slice 2 depends on slice 1.\n\n## §0 Implementation status\n\nEvery claim in this document is mapped to what exists in the tree.\n\n| Claim | Status | Where it stands |\n|---|---|---|\n| `web_fetch` tool (URL → readable text) | **Implemented** | `internal/tools/webfetch/{tool.go,webfetch.go}`; registered in `internal/app/archied/bootstrap.go` `registerStandaloneTools`, disabled-by-config returns `nil` |\n| **Web search** (query → result list) | **Aspirational — zero code** | No search provider, no search tool, no config block anywhere in the tree or in `ai-sdk` v0.1.32 |\n| `agent.Subagent` — nested agent in a fresh context window | **Implemented** (dependency) | `github.com/samcharles93/ai-sdk@v0.1.32/agent/subagent.go`. Synchronous, non-streaming, own model/system/toolset, `MaxSteps` defaults to 10, nesting depth capped at 5, returns final text only |\n| Subagent used in production | **Implemented, one consumer** | `internal/app/agentworker/review.go` — the adversarial reviewer. That is the only non-test use of `Subagent` in the repo |\n| A **delegate/subagent tool** on the chat surface | **Aspirational — zero code** | No `subagent`/`delegate` tool name is registered anywhere |\n| **Fan-out orchestration** (N missions, one collator) | **Aspirational — zero code** | `agentloop`'s package doc states it runs *one* mission: \"orchestration across missions lives with the caller\". No caller does this yet |\n| Parallel-safe tool execution | **Aspirational — zero code** | The unreachable `internal/tools/dispatch.go` dispatch/gating engine (`ExecutionClass`, `DispatchSequential`/`DispatchConcurrent`/`ClassifyEntry`) was deleted as dead code (tools-core-1); live concurrency is ai-sdk's `GenerateOptions.MaxParallelToolCalls`, which archie-core never sets |\n| Per-result caps + spill-to-disk | **Implemented** | `internal/agentexec/toolset.go` `ToolLimits{MaxResultChars,SpillDir}`, applied in `toolExecute` via `tools.CapPayload` (`limit.go`); no **aggregate** turn cap by design (`toolset.go`). `config.ToolPolicy.SpillDir`; default cap 50k chars, spill dir deliberately not defaulted |\n| Tool guardrails (repeat-failure / no-progress) | **Implemented, not on the call path** | `internal/tools/guardrail.go` engine exists. Its only non-test caller is `dispatchOne` — which is itself unreachable — so **the chat path never consults it**, and the agent path only records per *stage* (`domain/workflow/agent.go`) |\n| Structured capture tools (model reports into a typed store, not prose) | **Implemented** | `internal/app/agentworker/review.go` `record_finding` / `record_checked` — `core.NewTypedTool` appending to a caller-owned slice. This is the pattern a research source ledger should reuse |\n| Curator engine (interval, declared tool set, lifecycle) | **Implemented, tools broken** | `internal/domain/curator`; a curator declaring tools is **refused** at registration (`registry.go`, no `ToolBuilder` implementation) and `curatorLLMRunner` (`internal/app/archied/main.go`) drops `ChatRequest.Tools`. Budgets are time+concurrency only (`runtime.go`) — **no token budget** |\n| Cron / scheduling + delivery router | **Implemented, wired into the daemon** | `internal/domain/scheduling` (ticker engine), `internal/infrastructure/cronstore` (schema v2, `Kind` discriminator), and `internal/infrastructure/crondelivery`; `internal/app/archied/scheduling.go` composes them and `main.go` starts the engine. |\n| Workflow engines (multi-stage, resumable) | **Implemented, worktree-bound** | `internal/domain/workflow` — every non-triage workflow opens with `StagePrepareWorktree()` and mounts `tc.Dir` into a container; the task persists after every stage (`workflow.go`). `triage.go` documents there is \"no cheaper directory-less classification primitive\" |\n| Long-running chat-initiated work with progress | **Partial** | Chat turns run **once, synchronously**, inline in the channel's turn runner (`internal/gateway/turn.go`). Chat can spawn a *workflow task* (`task_spawn`) which is asynchronous — but that path is worktree/PR-shaped |\n| **Operator-push delivery of an async result** | **Aspirational — zero code** | Nothing pushes a finished result to a chat. No channel subscribes to the event bus (Telegram only *publishes* `KindTurnCompleted`); `crondelivery.Courier` is the intended seam but has **no implementation and no caller**; `send_file` works only inside the live turn. The one out-of-band notification in the tree is feasibility's n8n webhook (`feasibility.go`) |\n| Citation storage / sourLine truncated
},
{
"url": "/dev/prds/dynamic-curators/",
@@ -220,7 +226,7 @@
"url": "/dev/prds/eda-playbook-engine/",
"title": "EDA playbook engine -- design",
"section": "PRDs",
"body": "# EDA playbook engine -- design\n\n**Status:** Draft\n**Date:** 2026-09-03\n**Beads epic:** `archie-core-t2db`\n\n## Problem\n\n\"Which workflow runs for which trigger\" is hardcoded Go: a literal\nlabel vocabulary (`workintake.labelKinds`) and a literal label-\u003eworkflow map\n(`workflow/routing.go`), extended only by adding a Go case or shipping a\nskill whose `metadata.archie.workflow` overrides one *named* built-in\nworkflow. Extending the system to a new trigger, a new action, or a new\nevent source means a feature branch, a code change in a hardcoded\npath, and new Go tests -- for every addition. That is the barrier this\ndocument exists to remove.\n\nThe goal: triggers, the actions they run, and the\nconditions that connect them should be **drop-in and load**, not **drop-in\nand touch application code**. Yaegi-evaluated Go is the unit of imperative\n\"do a thing\" logic; YAML playbooks are pure orchestration data -- no logic,\njust \"on this event, with this data, call these actions, in this order,\nunder these conditions.\" The daemon's event coordinator doesn't know what a\n`bugfix` or `image-gen` action does, it resolves the name against a\nregistry and pipes typed data through.\n\nThis is explicitly **not** scoped to code-generation workflows. A playbook\naction can be any registered capability -- run a codegen workflow, send a\nmessage on a channel, open something on a forge, generate an image -- so\nlong as it's implemented behind one of the typed engine families below.\n\n## Relationship to existing decisions\n\n- `docs/prds/event-sources-and-reactions.md` ruled\n that reactions in the two epics it covers are **producer-only** (no veto,\n no mutation of in-flight work) and explicitly rejected a single generic\n `Source` interface as \"the untyped-hook shape the plugin engine rule\n exists to prevent.\" **This document extends that scope**: playbooks can\n dispatch to multiple typed action kinds, not just \"produce a\n `TaskEnvelope`.\" It does not relitigate producer-only-ness (still no\n veto/mutation of in-flight work here) and it does not introduce one\n generic interface -- see \"Typed positions, not one generic hook\" below,\n which is how it stays compliant with the plugin engine rule instead of\n reopening that document's #4.\n- `ARCHITECTURE.md#plugin-engine-rule-strict` governs every extension point\n introduced here. Every position below is a typed domain contract with an\n owning registry, not a generic callback map. This is a hard constraint,\n confirmed against the existing rule text before writing this doc.\n- Yaegi is already a proven in-process extension mechanism\n (`internal/plugin`, `internal/domain/workflow/wfeval/yaegi.go`,\n `internal/gate/gateeval/yaegi.go`, `internal/skill/plugin.go`) -- this\n design generalizes its existing role, it does not introduce a new\n execution mechanism.\n- `internal/domain/workflow/skillbuild.BuildRegistry` already composes a\n `workflow.Registry` from a skills catalog, plugin-defined overriding\n built-in. The playbook loader described here supersedes label routing\n specifically; it does not replace `skillbuild`'s workflow-composition role,\n it becomes an additional input the daemon composes at startup.\n- Webhook event intake is a separate design. This\n document defines the router each webhook-sourced event should be able to\n reach; it does not redesign webhook receipt itself.\n\n## Shape: four logic positions, each a typed engine family\n\nEvery entrypoint kind (mechanism, action, loop, schedule, route, trigger) is itself a schema emitter: defining a new kind produces the\ngenerated contract downstream tooling consumes. The kinds slot into a fixed\nhierarchy of logic positions:\n\n```\nWorkflow -\u003e Module -\u003e Channel (telegram/whatsapp/email/...)\n -\u003e Forge (GitHub/Gitea/GitLab/...)\n```\n\nEach position is its own typed engine family per the plugin engine rule:\nidentity + capability-specific operations, an owning `Registry`/`Manager`,\nexplicit lifecycle where the implementation owns resources, narrow host\naccess. Concretely:\n\n- **Workflow** -- already exists (`internal/domain/workflow`). A playbook\n action of kind `workflow` invokes a registered `workflow.Registry` entry\n by name, unchanged from the existing execution path.\n- **Module** -- the new general-purpose action position. A `Module` is a\n Yaegi-evaluated implementation of a generated interface (args in, typed\n result out) for one declared action kind (e.g. `image-gen`, `notify`,\n `open-pr-comment`). This is the position that makes actions \"not\n restricted to code-generation.\" Full design (schema-per-kind, the\n registry shape, the trust boundary, the recommended first slice):\n `docs/prds/module-position.md`.\n- **Channel** -- already exists as `channels.Channel` (telegram, email,\n webhook). A playbook action of kind `channel` sends through a named,\n already-registered Line truncated
"body": "# EDA playbook engine -- design\n\n**Status:** Draft\n**Date:** 2026-09-03\n**Beads epic:** `archie-core-t2db`\n\n## Problem\n\n\"Which workflow runs for which trigger\" is hardcoded Go: a literal\nlabel vocabulary (`workintake.labelKinds`) and a literal label-\u003eworkflow map\n(`workflow/routing.go`), extended only by adding a Go case or shipping a\nskill whose `metadata.archie.workflow` overrides one *named* built-in\nworkflow. Extending the system to a new trigger, a new action, or a new\nevent source means a feature branch, a code change in a hardcoded\npath, and new Go tests -- for every addition. That is the barrier this\ndocument exists to remove.\n\nThe goal: triggers, the actions they run, and the\nconditions that connect them should be **drop-in and load**, not **drop-in\nand touch application code**. Yaegi-evaluated Go is the unit of imperative\n\"do a thing\" logic; YAML playbooks are pure orchestration data -- no logic,\njust \"on this event, with this data, call these actions, in this order,\nunder these conditions.\" The daemon's event coordinator doesn't know what a\n`bugfix` or `image-gen` action does, it resolves the name against a\nregistry and pipes typed data through.\n\nThis is explicitly **not** scoped to code-generation workflows. A playbook\naction can be any registered capability -- run a codegen workflow, send a\nmessage on a channel, open something on a forge, generate an image -- so\nlong as it's implemented behind one of the typed engine families below.\n\n## Relationship to existing decisions\n\n- `docs/prds/event-sources-and-reactions.md` ruled\n that reactions in the two epics it covers are **producer-only** (no veto,\n no mutation of in-flight work) and explicitly rejected a single generic\n `Source` interface as \"the untyped-hook shape the plugin engine rule\n exists to prevent.\" **This document extends that scope**: playbooks can\n dispatch to multiple typed action kinds, not just \"produce a\n `TaskEnvelope`.\" It does not relitigate producer-only-ness (still no\n veto/mutation of in-flight work here) and it does not introduce one\n generic interface -- see \"Typed positions, not one generic hook\" below,\n which is how it stays compliant with the plugin engine rule instead of\n reopening that document's #4.\n- `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`\n governs every extension point\n introduced here. Every position below is a typed domain contract with an\n owning registry, not a generic callback map. This is a hard constraint,\n confirmed against the existing rule text before writing this doc.\n- Yaegi is already a proven in-process extension mechanism\n (`internal/plugin`, `internal/domain/workflow/wfeval/yaegi.go`,\n `internal/gate/gateeval/yaegi.go`, `internal/skill/plugin.go`) -- this\n design generalizes its existing role, it does not introduce a new\n execution mechanism.\n- `internal/domain/workflow/skillbuild.BuildRegistry` already composes a\n `workflow.Registry` from a skills catalog, plugin-defined overriding\n built-in. The playbook loader described here supersedes label routing\n specifically; it does not replace `skillbuild`'s workflow-composition role,\n it becomes an additional input the daemon composes at startup.\n- Webhook event intake is a separate design. This\n document defines the router each webhook-sourced event should be able to\n reach; it does not redesign webhook receipt itself.\n\n## Shape: four logic positions, each a typed engine family\n\nEvery entrypoint kind (mechanism, action, loop, schedule, route, trigger) is itself a schema emitter: defining a new kind produces the\ngenerated contract downstream tooling consumes. The kinds slot into a fixed\nhierarchy of logic positions:\n\n```\nWorkflow -\u003e Module -\u003e Channel (telegram/whatsapp/email/...)\n -\u003e Forge (GitHub/Gitea/GitLab/...)\n```\n\nEach position is its own typed engine family per the plugin engine rule:\nidentity + capability-specific operations, an owning `Registry`/`Manager`,\nexplicit lifecycle where the implementation owns resources, narrow host\naccess. Concretely:\n\n- **Workflow** -- already exists (`internal/domain/workflow`). A playbook\n action of kind `workflow` invokes a registered `workflow.Registry` entry\n by name, unchanged from the existing execution path.\n- **Module** -- the new general-purpose action position. A `Module` is a\n Yaegi-evaluated implementation of a generated interface (args in, typed\n result out) for one declared action kind (e.g. `image-gen`, `notify`,\n `open-pr-comment`). This is the position that makes actions \"not\n restricted to code-generation.\" Full design (schema-per-kind, the\n registry shape, the trust boundary, the recommended first slice):\n `docs/prds/module-position.md`.\n- **Channel** -- already exists as `channels.Channel` (telegram, email,\n webhook). A playbook action of kind `channel` sends through Line truncated
},
{
"url": "/dev/prds/embedded-nats/",
@@ -238,7 +244,7 @@
"url": "/dev/prds/event-sources-and-reactions/",
"title": "Event sources and reactions -- decision",
"section": "PRDs",
"body": "# Event sources and reactions -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-7d5u.1`, blocks `7d5u.2/.3/.4/.5`\n\nAnswers the four questions in `7d5u.1`'s description. Investigated against\nthe actual tree, not designed from scratch: three mechanisms already in this\ncodebase answer most of this, and the job here is picking the right one for\neach question and saying which packages change.\n\n## 1. In-process typed families, not out-of-process dispatch\n\nArchie has no out-of-process extension mechanism. The plugin engine\nrule (`ARCHITECTURE.md#plugin-engine-rule-strict`, mechanically checked by\n`internal/plugin/architecture_test.go`) keeps every capability family\nin-process behind a narrow typed registrar; NATS RPC exists for\ndaemon\u003c-\u003eagentexec, a different actor with a different trust boundary (task\nexecution, not third-party extension code), not a precedent for generic\nplugin dispatch. Neither epic's near-term payoff -- react to a labelled\nissue, bind a captured webhook to a workflow -- needs extension code in\nanother language or process. Building out-of-process dispatch now would be\ndesigning for a requirement neither epic states.\n\n`docs/architecture/plugins-and-extensions.md` does **not** need amending.\nThe line that looked like a blanket ban on hooks (`archie-core-7d5u`'s notes\nrecord the correction) is scoped to Workflow semantics specifically, and\nnothing decided here touches Workflow's ownership of its own contracts.\n\n## 2. Reaction delivery: `internal/eventbus`'s contract, a NEW stream\n\n`internal/eventbus.Publisher`/`Consumer` already has everything a reaction\nneeds: `PublishUnique(subject, idempotencyKey, payload)` for at-least-once\nwithout duplicate enqueue, `Ack`/`Nak` with \"a handler returning an error\ncauses redelivery.\" Do not design new delivery semantics; use this contract.\n\n**Do not reuse the existing `nats.Client` as-is.** `Config.StreamName` and\n`Config.Subjects` are already composition-supplied (\"the bus must not know\nwhich subjects belong to which domain,\" `config.go`), but the\nretention policy is not parameterized: `New` hardcodes\n`Retention: jetstream.WorkQueuePolicy` (`client.go`), the competing-consumer\npolicy correct for `ARCHIE_TASKS` task distribution -- one message, claimed by\nexactly one consumer -- and wrong for reactions. Two independent reactions\nboth wanting to see the same event under `WorkQueuePolicy` hit exactly the\ntrap `CLAUDE.md` already documents: overlapping filter subjects on a\nwork-queue stream mean the second consumer silently gets nothing. Reactions\nneed fan-out, not claim-once, so the client needs retention made a `Config`\nfield (defaulting to `WorkQueuePolicy` so `ARCHIE_TASKS` is\nunaffected), and a second stream (`ARCHIE_REACTIONS` or similar) configured\nunder a fan-out-capable policy, alongside the existing task-distribution\nstream -- not instead of it.\n\nThis is where `7d5u.2`'s embedded-vs-external axis attaches: whichever NATS\ninstance backs `ARCHIE_TASKS` also backs the reaction stream. NATS is not\noptional as a technology -- the choice is only\nwhether it runs as an external server or embedded in-process\n(`github.com/nats-io/nats-server/v2` is already a direct, test-proven\ndependency, just never wired into production startup). `7d5u.2` wires that;\nthis document does not re-decide it.\n\n## 3. Reactions in these two epics are producer-only\n\nNo veto, no mutation of in-flight work. Two existing shapes cover everything\neither epic actually needs, and neither is a hook that can block something\nelse:\n\n- **Cheap wake, no payload.** `internal/domain/curator/wake.go`'s\n `WakeOnPrimaryInput` subscribes to the lossy `events.Bus` and nudges a\n runtime to check sooner; a dropped event only delays a check-in, never\n loses work, because the trigger decision is a deterministic state read at\n pass time, not the event payload. Model any \"check something sooner\"\n reaction on this, unchanged.\n- **Produce new work, real payload.** `daemon.go`'s existing `pollNATS` -\u003e\n `publishTask` path is already exactly a reaction that observes forge state\n and produces a `workintake.TaskEnvelope`. A webhook source is a second\n producer into the same path, not a new capability -- see question 4.\n\nA reaction that can veto or mutate an *in-flight* task (block a PR from\nopening, alter a running stage) is a different, harder problem with its own\nordering and failure semantics, and belongs to `archie-core-h019` (adversarial\nself-review) if and when that epic needs one -- not here. Do not build a\ngeneral block-capable hook mechanism for either epic; nothing in their stated\nscope requires it, and it would duplicate whatever h019 eventually needs.\n\n## 4. No single generic intake interface; each domain keeps its own\n\nA `Source` interface generic enough to cover a forge issue, a chat message,\nand a cron tick would need an `any` payload -- theLine truncated
"body": "# Event sources and reactions -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-7d5u.1`, blocks `7d5u.2/.3/.4/.5`\n\nAnswers the four questions in `7d5u.1`'s description. Investigated against\nthe actual tree, not designed from scratch: three mechanisms already in this\ncodebase answer most of this, and the job here is picking the right one for\neach question and saying which packages change.\n\n## 1. In-process typed families, not out-of-process dispatch\n\nArchie has no out-of-process extension mechanism. The plugin engine\nrule (`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`,\nmechanically checked by\n`internal/plugin/architecture_test.go`) keeps every capability family\nin-process behind a narrow typed registrar; NATS RPC exists for\ndaemon\u003c-\u003eagentexec, a different actor with a different trust boundary (task\nexecution, not third-party extension code), not a precedent for generic\nplugin dispatch. Neither epic's near-term payoff -- react to a labelled\nissue, bind a captured webhook to a workflow -- needs extension code in\nanother language or process. Building out-of-process dispatch now would be\ndesigning for a requirement neither epic states.\n\n`docs/architecture/plugins-and-extensions.md` does **not** need amending.\nThe line that looked like a blanket ban on hooks (`archie-core-7d5u`'s notes\nrecord the correction) is scoped to Workflow semantics specifically, and\nnothing decided here touches Workflow's ownership of its own contracts.\n\n## 2. Reaction delivery: `internal/eventbus`'s contract, a NEW stream\n\n`internal/eventbus.Publisher`/`Consumer` already has everything a reaction\nneeds: `PublishUnique(subject, idempotencyKey, payload)` for at-least-once\nwithout duplicate enqueue, `Ack`/`Nak` with \"a handler returning an error\ncauses redelivery.\" Do not design new delivery semantics; use this contract.\n\n**Do not reuse the existing `nats.Client` as-is.** `Config.StreamName` and\n`Config.Subjects` are already composition-supplied (\"the bus must not know\nwhich subjects belong to which domain,\" `config.go`), but the\nretention policy is not parameterized: `New` hardcodes\n`Retention: jetstream.WorkQueuePolicy` (`client.go`), the competing-consumer\npolicy correct for `ARCHIE_TASKS` task distribution -- one message, claimed by\nexactly one consumer -- and wrong for reactions. Two independent reactions\nboth wanting to see the same event under `WorkQueuePolicy` hit exactly the\ntrap `CLAUDE.md` already documents: overlapping filter subjects on a\nwork-queue stream mean the second consumer silently gets nothing. Reactions\nneed fan-out, not claim-once, so the client needs retention made a `Config`\nfield (defaulting to `WorkQueuePolicy` so `ARCHIE_TASKS` is\nunaffected), and a second stream (`ARCHIE_REACTIONS` or similar) configured\nunder a fan-out-capable policy, alongside the existing task-distribution\nstream -- not instead of it.\n\nThis is where `7d5u.2`'s embedded-vs-external axis attaches: whichever NATS\ninstance backs `ARCHIE_TASKS` also backs the reaction stream. NATS is not\noptional as a technology -- the choice is only\nwhether it runs as an external server or embedded in-process\n(`github.com/nats-io/nats-server/v2` is already a direct, test-proven\ndependency, just never wired into production startup). `7d5u.2` wires that;\nthis document does not re-decide it.\n\n## 3. Reactions in these two epics are producer-only\n\nNo veto, no mutation of in-flight work. Two existing shapes cover everything\neither epic actually needs, and neither is a hook that can block something\nelse:\n\n- **Cheap wake, no payload.** `internal/domain/curator/wake.go`'s\n `WakeOnPrimaryInput` subscribes to the lossy `events.Bus` and nudges a\n runtime to check sooner; a dropped event only delays a check-in, never\n loses work, because the trigger decision is a deterministic state read at\n pass time, not the event payload. Model any \"check something sooner\"\n reaction on this, unchanged.\n- **Produce new work, real payload.** `daemon.go`'s existing `pollNATS` -\u003e\n `publishTask` path is already exactly a reaction that observes forge state\n and produces a `workintake.TaskEnvelope`. A webhook source is a second\n producer into the same path, not a new capability -- see question 4.\n\nA reaction that can veto or mutate an *in-flight* task (block a PR from\nopening, alter a running stage) is a different, harder problem with its own\nordering and failure semantics, and belongs to `archie-core-h019` (adversarial\nself-review) if and when that epic needs one -- not here. Do not build a\ngeneral block-capable hook mechanism for either epic; nothing in their stated\nscope requires it, and it would duplicate whatever h019 eventually needs.\n\n## 4. No single generic intake interface; each domain keeps its own\n\nA `Source` interface generic enough to cover a forge issue, a chat message,\nand a cron tick wouldLine truncated
},
{
"url": "/dev/prds/extensions-center/",
@@ -256,7 +262,7 @@
"url": "/dev/prds/image-capability-contract/",
"title": "Image capability contract and configuration",
"section": "PRDs",
"body": "# Image capability contract and configuration\n\n**Status:** Approved\n\nEpic: archie-core-1786748942120-1-6636e629 / GitHub #496 (\"Image generation\ncapability: hosted API baseline plus local GPU workflows\").\n\nThe contract and configuration (#497) shipped first and is settled — see\n\"Package: `internal/domain/image`\" below. This document now covers the full\nfeature set: hosted provider (#498), local GPU provider (#499), `/image`\nrouting and clarification (#500), delivery through channels and web (#501).\nDocumentation (#502) and the cross-cutting test matrix (#503) are execution\nwork against the design below, not open design questions, so they are not\ngiven their own sections — each preceding section states its own test\nobligations inline.\n\n## Problem\n\nArchie needs a provider-neutral boundary for image generation/editing so a\nhosted API (gpt-image-2-class) and a future local GPU backend can both\nimplement it without either one leaking into the domain contract. Nothing\nin the repo defines this (`grep -ri image` over `internal/domain` and\n`internal/config` returns nothing image-specific).\n\n## Design\n\nFollows the plugin engine family shape already established by\n`internal/domain/curator` and `internal/domain/memory` (ARCHITECTURE.md\n\"plugin engine rule strict\"): a typed contract with real domain operations,\nan owning `Registry` (register/get/names, no start/stop lifecycle — see\nbelow), and narrow host access via a `Registrar`.\n\n### Package: `internal/domain/image`\n\n**Why no `Lifecycle` (`Start/Health/Stop`)**: curator and memory engines are\nlong-running — they hold a background cadence or a persistent connection\nworth health-checking. An image provider is call-scoped: it either serves a\n`Generate`/`Edit` request or it does not. Health here means \"is this\nprovider usable at call time\", which is exactly what `Generate`/`Edit`\nreturning a typed `ErrUnavailable` already communicates — a separate\n`Health()` poll would just duplicate that. `Registry` still owns\nregistration and lookup, so provider selection is testable with fakes per\nthe acceptance criteria, but there is no `Start`/`Stop` to orchestrate.\n\n```go\n// Capability declares what one provider supports, discoverable before a\n// request is built so a caller can reject an unsupported combination (e.g.\n// edit-with-mask on a generate-only provider) instead of sending it and\n// parsing a provider-specific error back out.\ntype Capability struct {\n Generate bool\n Edit bool // edit requires at least one input image\n Mask bool // edit supports a mask restricting the edited region\n MaxInputs int // 0 = Edit unsupported\n Sizes []string // provider-declared output sizes, e.g. \"1024x1024\"\n}\n\n// Provider is the typed contract every image backend implements — hosted\n// (gpt-image-2-class) or local (GPU recipe). No Lifecycle: a provider is\n// call-scoped, not long-running (see design doc rationale).\ntype Provider interface {\n Name() string\n // Class distinguishes hosted (spends money/quota per call) from local\n // (spends host GPU/time). Selection logic and config validation key off\n // this, never off Name, so a new provider cannot silently slip through\n // the hosted-cost gate under an unrecognized name.\n Class() ProviderClass\n Capability() Capability\n Generate(ctx context.Context, req GenerateRequest) (Result, error)\n Edit(ctx context.Context, req EditRequest) (Result, error)\n}\n\ntype ProviderClass string\n\nconst (\n ClassHosted ProviderClass = \"hosted\"\n ClassLocal ProviderClass = \"local\"\n)\n```\n\nRequest/result types (provider-neutral, no OpenAI types):\n\n```go\ntype GenerateRequest struct {\n Prompt string\n Size string // \"\" = provider default\n N int // number of images; 0 = 1\n Options map[string]string // provider-specific overflow (e.g. \"quality\"),\n // deliberately untyped so the contract does not\n // grow a field per provider\n}\n\ntype EditRequest struct {\n Prompt string\n Inputs []ImageData // 1..Capability.MaxInputs\n Mask *ImageData // nil unless Capability.Mask\n Size string\n N int\n Options map[string]string\n}\n\n// ImageData carries image bytes in-process, never a path or URL: the\n// domain layer must not assume a filesystem or a fetchable location (mirrors\n// why curator's Registrar never receives *daemon.Daemon — no ambient host\n// access smuggled in through a \"just a string\" field).\ntype ImageData struct {\n Bytes []byte\n MIMEType string\n}\n\ntype Result struct {\n Images []ImageData\n Provider string\n Model string\n CreatedAt time.Time\n}\n```\n\n### Error taxonomy\n\n```go\nvar (\n ErrUnavailable = errors.New(\"image provider unavailable\") // missing credential, backend down\n ErrUnsupporteLine truncated
"body": "# Image capability contract and configuration\n\n**Status:** Approved\n\nEpic: archie-core-1786748942120-1-6636e629 / GitHub #496 (\"Image generation\ncapability: hosted API baseline plus local GPU workflows\").\n\nThe contract and configuration (#497) shipped first and is settled — see\n\"Package: `internal/domain/image`\" below. This document now covers the full\nfeature set: hosted provider (#498), local GPU provider (#499), `/image`\nrouting and clarification (#500), delivery through channels and web (#501).\nDocumentation (#502) and the cross-cutting test matrix (#503) are execution\nwork against the design below, not open design questions, so they are not\ngiven their own sections — each preceding section states its own test\nobligations inline.\n\n## Problem\n\nArchie needs a provider-neutral boundary for image generation/editing so a\nhosted API (gpt-image-2-class) and a future local GPU backend can both\nimplement it without either one leaking into the domain contract. Nothing\nin the repo defines this (`grep -ri image` over `internal/domain` and\n`internal/config` returns nothing image-specific).\n\n## Design\n\nFollows the plugin engine family shape already established by\n`internal/domain/curator` and `internal/domain/memory`\n(`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`): a\ntyped contract with real domain operations,\nan owning `Registry` (register/get/names, no start/stop lifecycle — see\nbelow), and narrow host access via a `Registrar`.\n\n### Package: `internal/domain/image`\n\n**Why no `Lifecycle` (`Start/Health/Stop`)**: curator and memory engines are\nlong-running — they hold a background cadence or a persistent connection\nworth health-checking. An image provider is call-scoped: it either serves a\n`Generate`/`Edit` request or it does not. Health here means \"is this\nprovider usable at call time\", which is exactly what `Generate`/`Edit`\nreturning a typed `ErrUnavailable` already communicates — a separate\n`Health()` poll would just duplicate that. `Registry` still owns\nregistration and lookup, so provider selection is testable with fakes per\nthe acceptance criteria, but there is no `Start`/`Stop` to orchestrate.\n\n```go\n// Capability declares what one provider supports, discoverable before a\n// request is built so a caller can reject an unsupported combination (e.g.\n// edit-with-mask on a generate-only provider) instead of sending it and\n// parsing a provider-specific error back out.\ntype Capability struct {\n Generate bool\n Edit bool // edit requires at least one input image\n Mask bool // edit supports a mask restricting the edited region\n MaxInputs int // 0 = Edit unsupported\n Sizes []string // provider-declared output sizes, e.g. \"1024x1024\"\n}\n\n// Provider is the typed contract every image backend implements — hosted\n// (gpt-image-2-class) or local (GPU recipe). No Lifecycle: a provider is\n// call-scoped, not long-running (see design doc rationale).\ntype Provider interface {\n Name() string\n // Class distinguishes hosted (spends money/quota per call) from local\n // (spends host GPU/time). Selection logic and config validation key off\n // this, never off Name, so a new provider cannot silently slip through\n // the hosted-cost gate under an unrecognized name.\n Class() ProviderClass\n Capability() Capability\n Generate(ctx context.Context, req GenerateRequest) (Result, error)\n Edit(ctx context.Context, req EditRequest) (Result, error)\n}\n\ntype ProviderClass string\n\nconst (\n ClassHosted ProviderClass = \"hosted\"\n ClassLocal ProviderClass = \"local\"\n)\n```\n\nRequest/result types (provider-neutral, no OpenAI types):\n\n```go\ntype GenerateRequest struct {\n Prompt string\n Size string // \"\" = provider default\n N int // number of images; 0 = 1\n Options map[string]string // provider-specific overflow (e.g. \"quality\"),\n // deliberately untyped so the contract does not\n // grow a field per provider\n}\n\ntype EditRequest struct {\n Prompt string\n Inputs []ImageData // 1..Capability.MaxInputs\n Mask *ImageData // nil unless Capability.Mask\n Size string\n N int\n Options map[string]string\n}\n\n// ImageData carries image bytes in-process, never a path or URL: the\n// domain layer must not assume a filesystem or a fetchable location (mirrors\n// why curator's Registrar never receives *daemon.Daemon — no ambient host\n// access smuggled in through a \"just a string\" field).\ntype ImageData struct {\n Bytes []byte\n MIMEType string\n}\n\ntype Result struct {\n Images []ImageData\n Provider string\n Model string\n CreatedAt time.Time\n}\n```\n\n### Error taxonomy\n\n```go\nvar (\n ErrUnavailable = errors.New(\"image provider unavailable\") // missing credential, backLine truncated
},
{
"url": "/dev/prds/inline-review/",
@@ -274,7 +280,7 @@
"url": "/dev/prds/memory-engine-unification/",
"title": "Memory engine unification: four scopes, CRUD, and one write path -- decision",
"section": "PRDs",
"body": "# Memory engine unification: four scopes, CRUD, and one write path -- decision\n\n**Status:** Approved\n**Date:** 2026-09-16\n**Findings:** `memory-4` and its dependants in the adversarial sweep\n(`.local/issue-tracker`); the real defect is the split described below, for\nwhich `memory-4` is a symptom\n**Supersedes:** the draft `memory-turn-context.md` (its synchronous-read\nargument survives and is reused; its `Manager` method and consumer-owned port do\nnot)\n**Settles:** four open items in `docs/architecture/migration-decisions.md#5`\n(listed at the end)\n\n## Problem\n\nThere are **two live memory stores for one assistant**, split by which component\nwrites them, and the chat turn reads neither.\n\n| Family | Written by | Root | Format |\n|---|---|---|---|\n| `internal/memory` (`Manager`, `builtin.Provider`) | the chat agent's `memory_edit` tool via `memorytoolprovider` (`bootstrap.go`) | `\u003cworkDir\u003e/memory` | `MEMORY.md` / `USER.md` |\n| `internal/domain/memory` + `internal/infrastructure/memory` | the session curator (`sessioncurator.go`) | `\u003cworkDir\u003e/memory-engine` | identity-keyed blocks |\n\nThey share no code, no format and no scope vocabulary. Neither reaches a prompt:\n`Manager.SystemPromptBlock` (`internal/memory/manager.go`) has no production\ncaller anywhere, so the agent can write memory through a tool and never read it\nback.\n\nThree further defects fall out of the same split:\n\n1. **The engine's contract is not CRUD.** `Store` is `Write`/`Query`/`List`/\n `Forget` — create, read, delete, and **no Update**. The retired file provider\n *does* have `handleAdd`/`handleReplace`/`handleRemove`, so the family being\n deleted is operationally richer than its replacement.\n2. **There is no scope model.** The contract carries one opaque `Identity\n string`, and the curator fills it with a **session id** (`sessioncurator.go`)\n — which is none of the four scopes `docs/architecture/agent-system.md`\n requires, and stops meaning anything when the session ends.\n3. **The chat turn has no user identity on half the channels.** Telegram and\n email populate `SenderID` with a person; the dashboard populates it with\n nothing, and a webhook populates it with nothing either — a route path names\n a source, not a person, so `webhook.go` leaves `SenderID` empty and carries\n the route in `Inbound.BudgetKey` for rate limiting. `sender_id` is persisted\n (`session_store_sqlite.go`), so whatever a channel puts there reaches the\n consumers that read it.\n\n`agent-system.md` says the write-scope selection and cross-scope sharing\nrules \"require a focused memory design decision\". This is that decision.\n\n## Decision\n\n### 1. One engine, addressed by four typed scopes\n\n`internal/domain/memory` is the only memory engine. `Observation.Identity`,\n`Query.Identity`, `Record.Identity` and `List(identity)` are deleted, not\nextended: a field whose meaning depends on the caller cannot carry a scope.\n\n```go\ntype ScopeKind string\n\nconst (\n ScopeGlobal ScopeKind = \"global\" // shared across the application\n ScopeAgent ScopeKind = \"agent\" // private to one Agent\n ScopeUser ScopeKind = \"user\" // one user, across their Agents\n ScopeAgentUser ScopeKind = \"agent-user\" // one Agent's relationship with one user\n)\n\ntype Scope struct {\n Kind ScopeKind\n Agent AgentID // required for ScopeAgent, ScopeAgentUser\n User IdentityID // required for ScopeUser, ScopeAgentUser\n}\n\nfunc (s Scope) Validate() error // rejects a component present where it is not required\nfunc (s Scope) Key() string // canonical, collision-free storage key\n```\n\n`AgentID` and `IdentityID` are opaque. This package never resolves or\ncanonicalises them.\n\nA turn's resolved identity is one value:\n\n```go\ntype Subject struct {\n AgentID AgentID\n UserID IdentityID // \"\" when the channel carries no per-person identity\n}\n\nfunc (s Subject) Scopes() []Scope // readable, most specific first\nfunc (s Subject) WritableScopes() []Scope // never includes ScopeGlobal\n```\n\n**Access control is naming a scope, and nothing else.** The read path names\nexactly the scopes of the resolved `Subject`; the engine never unions beyond what\nit is handed and applies no policy of its own. An engine that enforced policy\nwould need to know about channels, sessions and bindings, and every backend would\nreimplement it. \"Agent-wide is private to its owning Agent by default\"\n(`agent-system.md`) falls out mechanically, because `ScopeAgent{a}` and\n`ScopeAgent{b}` are different storage keys.\n\n`ScopeGlobal` is never model-writable. Writing it is an operator action; nothing\nproduces one yet, but the contract models it because the read set includes it.\n\n### 2. CRUD, with revisions retained\n\n```go\ntype Store interface {\n Create(ctx context.Context, in NewRecord) (Record, error)\n Get(ctx context.Context,Line truncated
"body": "# Memory engine unification: four scopes, CRUD, and one write path -- decision\n\n**Status:** Approved\n**Date:** 2026-09-16\n**Findings:** `memory-4` and its dependants in the adversarial sweep\n(`.local/issue-tracker`); the real defect is the split described below, for\nwhich `memory-4` is a symptom\n**Supersedes:** the draft `memory-turn-context.md` (its synchronous-read\nargument survives and is reused; its `Manager` method and consumer-owned port do\nnot)\n**Settles:** four open items in `docs/architecture/migration-decisions.md#5`\n(listed at the end)\n\n## Problem\n\nThere are **two live memory stores for one assistant**, split by which component\nwrites them, and the chat turn reads neither.\n\n| Family | Written by | Root | Format |\n|---|---|---|---|\n| `internal/memory` (`Manager`, `builtin.Provider`) | the chat agent's `memory_edit` tool via `memorytoolprovider` (`bootstrap.go`) | `\u003cworkDir\u003e/memory` | `MEMORY.md` / `USER.md` |\n| `internal/domain/memory` + `internal/infrastructure/memory` | the session curator (`sessioncurator.go`) | `\u003cworkDir\u003e/memory-engine` | identity-keyed blocks |\n\nThey share no code, no format and no scope vocabulary. Neither reaches a prompt:\n`Manager.SystemPromptBlock` (`internal/memory/manager.go`) has no production\ncaller anywhere, so the agent can write memory through a tool and never read it\nback.\n\nThree further defects fall out of the same split:\n\n1. **The engine's contract is not CRUD.** `Store` is `Write`/`Query`/`List`/\n `Forget` — create, read, delete, and **no Update**. The retired file provider\n *does* have `handleAdd`/`handleReplace`/`handleRemove`, so the family being\n deleted is operationally richer than its replacement.\n2. **There is no scope model.** The contract carries one opaque `Identity\n string`, and the curator fills it with a **session id** (`sessioncurator.go`)\n — which is none of the four scopes `docs/architecture/agent-system.md`\n requires, and stops meaning anything when the session ends.\n3. **The chat turn has no user identity on half the channels.** Telegram and\n email populate `SenderID` with a person; the dashboard populates it with\n nothing, and a webhook populates it with nothing either — a route path names\n a source, not a person, so `webhook.go` leaves `SenderID` empty and carries\n the route in `Inbound.BudgetKey` for rate limiting. `sender_id` is persisted\n (`session_store_sqlite.go`), so whatever a channel puts there reaches the\n consumers that read it.\n\n`agent-system.md` says the write-scope selection and cross-scope sharing\nrules \"require a focused memory design decision\". This is that decision.\n\n## Decision\n\n### 1. One engine, addressed by four typed scopes\n\n`internal/domain/memory` is the only memory engine. `Observation.Identity`,\n`Query.Identity`, `Record.Identity` and `List(identity)` are deleted, not\nextended: a field whose meaning depends on the caller cannot carry a scope.\n\n```go\ntype ScopeKind string\n\nconst (\n ScopeGlobal ScopeKind = \"global\" // shared across the application\n ScopeAgent ScopeKind = \"agent\" // private to one Agent\n ScopeUser ScopeKind = \"user\" // one user, across their Agents\n ScopeAgentUser ScopeKind = \"agent-user\" // one Agent's relationship with one user\n)\n\ntype Scope struct {\n Kind ScopeKind\n Agent AgentID // required for ScopeAgent, ScopeAgentUser\n User IdentityID // required for ScopeUser, ScopeAgentUser\n}\n\nfunc (s Scope) Validate() error // rejects a component present where it is not required\nfunc (s Scope) Key() string // canonical, collision-free storage key\n```\n\n`AgentID` and `IdentityID` are opaque. This package never resolves or\ncanonicalises them.\n\nA turn's resolved identity is one value:\n\n```go\ntype Subject struct {\n AgentID AgentID\n UserID IdentityID // \"\" when the channel carries no per-person identity\n}\n\nfunc (s Subject) Scopes() []Scope // readable, most specific first\nfunc (s Subject) WritableScopes() []Scope // never includes ScopeGlobal\n```\n\n**Access control is naming a scope, and nothing else.** The read path names\nexactly the scopes of the resolved `Subject`; the engine never unions beyond what\nit is handed and applies no policy of its own. An engine that enforced policy\nwould need to know about channels, sessions and bindings, and every backend would\nreimplement it. \"Agent-wide is private to its owning Agent by default\"\n(`agent-system.md`) falls out mechanically, because `ScopeAgent{a}` and\n`ScopeAgent{b}` are different storage keys.\n\n`ScopeGlobal` is never model-writable. Writing it is an operator action; nothing\nproduces one yet, but the contract models it because the read set includes it.\n\n### 2. CRUD, with revisions retained\n\n```go\ntype Store interface {\n Create(ctx context.Context, in NewRecord) (Record, error)\n Get(ctx context.Context,Line truncated
},
{
"url": "/dev/prds/messaging-service-boundary/",
@@ -298,7 +304,7 @@
"url": "/dev/prds/news-and-releases/",
"title": "Public news and per-version release notes -- decision",
"section": "PRDs",
"body": "# Public news and per-version release notes -- decision\n\n**Status:** Approved\n**Date:** 2026-09-21\n**Beads issue:** `archie-core-2ncm.2`\n\nA public news page and a release-notes page for every version. Both are derived\nfrom the changelogs the release process already produces, so publishing a\nrelease adds no writing. Part A is the derivation and the artifact any renderer\nconsumes; it is not tied to MkDocs. Part B is the MkDocs rendering that\npublishes them at `offloaded.dev/news/`.\n\n## Part A -- release facts and their derivation\n\n### Source of truth\n\nRelease notes come from `CHANGELOG.archied.md` and `CHANGELOG.archie.md`. Those\nare the release process's frozen notes: `tools/release.sh --prepare` writes a\nsection, the maintainer edits it, and `--tag` refuses to tag a version without\nits section. A page exists exactly for a release the process cut, and no second\ncopy of release prose can drift from the changelog.\n\nTags are not the source. CI and deployment check out shallow, so tags are absent\nfrom a site build; the changelogs are always present and their\n`## [\u003cversion\u003e] - \u003cdate\u003e` headings carry the same version and date the tags\ncarry. Raw commits are not the source either: the changelog is the edited text,\nnot the commit list.\n\n### What a version's notes contain\n\nThe version and date parsed from the section heading, and the section body\nunchanged. The body keeps the maintainer's headings and bullets; the generator\ndoes not regroup them into feature and fix categories, because those categories\nexist only on commits the edited changelog does not preserve.\n\n`## [Unreleased]` is skipped. Any other `## [` heading that is not\n`[version] - date` stops generation, so a malformed heading cannot silently drop\na release. A relative Markdown link in a body stops generation too: a rendered\npage sits at a different depth from the changelog, and a host's link checking\nwould fail on the dead link. Absolute links pass through.\n\n### Two components\n\n`archied` and `archie-agent` version independently and either can be held back,\nso the data carries the tag prefix (`archied`, `archie`), the product name\n(`archied`, `archie-agent`), and the version as separate fields. A release that\nmoved one component is one entry. The generator never pairs two component\nversions or invents a combined product version.\n\n### The canonical artifact\n\n`docs/news/releases.json` is the host hand-off: a committed, generated,\nnewest-first array of `{component, name, version, date, body}`. Every adapter\nrenders from this file rather than re-parsing a changelog. The JSON is the\ncontract; a host adapter may add markup, but not facts.\n\n### Zero per-release maintenance\n\n`task news` regenerates the JSON and the MkDocs pages from the changelogs.\n`task news:check` regenerates them in a temporary directory and fails when the\ncommitted files differ; it runs in `task check`, so a changelog edit cannot land\nwithout its regeneration. `tools/release.sh --tag` regenerates and stages them\nin the release commit, so a tag's tree carries its own facts.\n\nThe generator owns `docs/news/releases.json`, `docs/news/index.md` and the two\ncomponent directories end-to-end: it rewrites expected files and reports an\nunexpected file in a component directory as drift. It leaves every other file\nunder `docs/news/` alone, so a future hand-written announcement is not its\nbusiness.\n\n## Part B -- publishing\n\nMkDocs is the host. `docs/news/index.md` is the news page: date-grouped, newest\nfirst, one entry per release carrying the component, the version, and a link to\nits notes. `docs/news/archied/\u003cversion\u003e.md` and `docs/news/archie/\u003cversion\u003e.md`\nhold the notes. `site_url` is `https://offloaded.dev/`, so the pages are served\nat `offloaded.dev/news/`.\n\nThe version pages stay out of the derived navigation (`not_in_nav` in\n`mkdocs.yml`) while remaining published; the news page is their entry point, so\na version list that grows with every release cannot push the architecture tree\noff the screen.\n\nA different renderer would read `docs/news/releases.json` instead of these\nMarkdown files. That is a separate change in that renderer's repository and\ndoes not alter Part A; the JSON, not the Markdown, is the reusable half.\n\n## Not in scope\n\n- Generated summaries, categories, or section headings; the changelog has no\n structured summary field to derive one from.\n- Per-release download or install links; where to get the artifacts is\n documented once, not restated for every version.\n- Hand-written news items. The generated page lists releases.\n- Changes to `infra/ansible`. Serving the site at a hostname other than\n `offloaded.dev` is an infrastructure decision.\n\n## Verification\n\n- `go test ./tools/newsgen/...` covers parsing, ordering, rendering, the link\n and heading refusals, and check-mode drift.\n- `task news:check` passes inside `task check`.\nLine truncated
"body": "# Public news and per-version release notes -- decision\n\n**Status:** Approved\n**Date:** 2026-09-21\n**Beads issue:** `archie-core-2ncm.2`\n**Superseded in part:** `docs/prds/release-stream-and-commit-rules.md` supersedes the\nsections \"Source of truth\" and \"Two components\" below. There is now one release\nstream: a single `CHANGELOG.md` carries every release section, the per-component\n`CHANGELOG.archied.md` and `CHANGELOG.archie.md` are deleted, and one `vX.Y.Z` tag\nnames a release. The rest of this document still holds.\n\nA public news page and a release-notes page for every version. Both are derived\nfrom the changelogs the release process already produces, so publishing a\nrelease adds no writing. Part A is the derivation and the artifact any renderer\nconsumes; it is not tied to MkDocs. Part B is the MkDocs rendering that\npublishes them at `offloaded.dev/news/`.\n\n## Part A -- release facts and their derivation\n\n### Source of truth\n\nRelease notes come from `CHANGELOG.archied.md` and `CHANGELOG.archie.md`. Those\nare the release process's frozen notes: `tools/release.sh --prepare` writes a\nsection, the maintainer edits it, and `--tag` refuses to tag a version without\nits section. A page exists exactly for a release the process cut, and no second\ncopy of release prose can drift from the changelog.\n\nTags are not the source. CI and deployment check out shallow, so tags are absent\nfrom a site build; the changelogs are always present and their\n`## [\u003cversion\u003e] - \u003cdate\u003e` headings carry the same version and date the tags\ncarry. Raw commits are not the source either: the changelog is the edited text,\nnot the commit list.\n\n### What a version's notes contain\n\nThe version and date parsed from the section heading, and the section body\nunchanged. The body keeps the maintainer's headings and bullets; the generator\ndoes not regroup them into feature and fix categories, because those categories\nexist only on commits the edited changelog does not preserve.\n\n`## [Unreleased]` is skipped. Any other `## [` heading that is not\n`[version] - date` stops generation, so a malformed heading cannot silently drop\na release. A relative Markdown link in a body stops generation too: a rendered\npage sits at a different depth from the changelog, and a host's link checking\nwould fail on the dead link. Absolute links pass through.\n\n### Two components\n\n`archied` and `archie-agent` version independently and either can be held back,\nso the data carries the tag prefix (`archied`, `archie`), the product name\n(`archied`, `archie-agent`), and the version as separate fields. A release that\nmoved one component is one entry. The generator never pairs two component\nversions or invents a combined product version.\n\n### The canonical artifact\n\n`docs/news/releases.json` is the host hand-off: a committed, generated,\nnewest-first array of `{component, name, version, date, body}`. Every adapter\nrenders from this file rather than re-parsing a changelog. The JSON is the\ncontract; a host adapter may add markup, but not facts.\n\n### Zero per-release maintenance\n\n`task news` regenerates the JSON and the MkDocs pages from the changelogs.\n`task news:check` regenerates them in a temporary directory and fails when the\ncommitted files differ; it runs in `task check`, so a changelog edit cannot land\nwithout its regeneration. `tools/release.sh --tag` regenerates and stages them\nin the release commit, so a tag's tree carries its own facts.\n\nThe generator owns `docs/news/releases.json`, `docs/news/index.md` and the two\ncomponent directories end-to-end: it rewrites expected files and reports an\nunexpected file in a component directory as drift. It leaves every other file\nunder `docs/news/` alone, so a future hand-written announcement is not its\nbusiness.\n\n## Part B -- publishing\n\nMkDocs is the host. `docs/news/index.md` is the news page: date-grouped, newest\nfirst, one entry per release carrying the component, the version, and a link to\nits notes. `docs/news/archied/\u003cversion\u003e.md` and `docs/news/archie/\u003cversion\u003e.md`\nhold the notes. `site_url` is `https://offloaded.dev/`, so the pages are served\nat `offloaded.dev/news/`.\n\nThe version pages stay out of the derived navigation (`not_in_nav` in\n`mkdocs.yml`) while remaining published; the news page is their entry point, so\na version list that grows with every release cannot push the architecture tree\noff the screen.\n\nA different renderer would read `docs/news/releases.json` instead of these\nMarkdown files. That is a separate change in that renderer's repository and\ndoes not alter Part A; the JSON, not the Markdown, is the reusable half.\n\n## Not in scope\n\n- Generated summaries, categories, or section headings; the changelog has no\n structured summary field to derive one from.\n- Per-release download or install links; where to get the artifacts is\n documented once, not restated for eveLine truncated
},
{
"url": "/dev/prds/operator-pr-review/",
@@ -364,7 +370,7 @@
"url": "/dev/prds/service-decomposition/",
"title": "Service decomposition -- decision",
"section": "PRDs",
"body": "# Service decomposition -- decision\n\n**Status:** Draft\n**Date:** 2026-09-05\n**Beads epic:** archie-core-8cda\n**Prior art:** `docs/inspiration/2026-09-05-awx-service-decomposition-and-ansible-task-model.md`,\n`docs/inspiration/module-reference-awx-decomposition-vs-archie.md`,\n`docs/inspiration/service-discovery-research-2026-09-05.md`,\n`/work/artefacts/archie-core-current-state-archify.html`,\n`/work/artefacts/archie-core-ideal-state-archify.html`\n\nThe Phase 3 UI boundary and configuration decision is ratified in\n[`ui-service-boundary.md`](/dev/prds/ui-service-boundary/). That focused document is\nthe implementation authority for `archie-core-8cda.5.2`; this parent remains\nthe broader service-distribution proposal.\n\n## Decision\n\narchie-core moves from one Go binary (`archied`) hosting every domain\nin-process to a set of independently deployable services, each exposing\nexactly one typed contract. Consumers depend on the contract; they never\nreach into another service's internal types, session state, or config.\ngRPC is the synchronous transport; NATS remains for asynchronous fan-out\n(status, telemetry) rather than being replaced.\n\nThis is a **distribution decision**, not a rewrite of Archie's domain\nmodel. The six-domain split already approved in\n`docs/architecture/index.md` and `docs/architecture/organisation.md`\n(Identity, Agent, Messaging, Workflow, Work Intake, Plugin) is unchanged;\nthis PRD is about how the *processes* running that domain logic get\npackaged, contracted, and discovered -- not about redrawing domain\nboundaries.\n\n### Target services\n\n| Service | Contract it owns | Existing code it replaces/wraps |\n|---|---|---|\n| UI Service | thin client only; talks to Gateway and State Store contracts | `internal/webui` (SPA hosting stays; API surface becomes typed contract clients, not a peer with direct access) |\n| Gateway Service | routing / turn / session contract | `internal/gateway` |\n| Messaging Service | channel-plugin contract (Telegram, email, Discord, Teams, ...) | `internal/channels` |\n| Curator Service | curator contract; **optional**, installs as a Gateway plugin | `internal/domain/curator` |\n| Scheduler Service | cron/ticker contract | `internal/domain/scheduling` |\n| Execution Environment | execution-dispatch contract | `internal/domain/workflow`, task dispatch paths |\n| Runner | isolated worktree/container execution | `internal/container`, `internal/agentexec`, `internal/worktree` |\n| State Store | state-access contract | `internal/store` |\n\n### Discovery\n\nPer `docs/inspiration/service-discovery-research-2026-09-05.md`:\n\n- **Primary:** Kubernetes-native discovery (Service + headless-Service/DNS\n + EndpointSlice, served by CoreDNS), delivered as a Helm chart + Operator,\n on k3s for single-host installs and a real cluster for multi-host or a\n hosted offering.\n- **Fallback:** NATS-based discovery (micro `$SRV` announce + JetStream KV\n registry) for no-K8s single-host installs, with a custom gRPC resolver\n reading `host:port` from the KV bucket.\n- Both implementations sit behind one internal interface:\n\n ```go\n type ServiceRegistry interface {\n Resolve(service string) []Endpoint\n Watch(service string) \u003c-chan Event // join/leave\n }\n ```\n\n- An optional service (Curator; others later) that is not installed\n must resolve to a distinct `NotInstalled` outcome, never a `Down`/\n `Unhealthy` one. Under K8s this falls out of DNS returning no record;\n under the NATS fallback it requires an explicit \"installed\" marker in the\n KV registry, not just absence-implies-down.\n\n### Distribution model this supports\n\nBoth self-hosted (customer runs the Helm chart or the NATS-fallback\nbinaries themselves) and a managed/hosted offering (we run the same Helm\nchart) are in scope -- this is the RHEL / Ansible Automation Platform\nmodel: one architecture, sold both ways. This PRD does not decide the\nbusiness model; it decides that the architecture must not foreclose\neither shape.\n\n## Why this shape\n\n`docs/inspiration/module-reference-awx-decomposition-vs-archie.md`\nestablished that Archie's existing domain split already does what AWX's\nservice-decomposition post argues for -- boundaries exist. What didn't\nexist was deployability: `internal/webui` was not a passive frontend. The\nre-baselined coupling inventory is below, and the ratified boundary is\n[`ui-service-boundary.md`](/dev/prds/ui-service-boundary/).\n\n- Telegram task actions now call Gateway's `ChatContract` directly through\n `chatTaskActorAdapter`; the old Telegram-to-webui HTTP detour is historical.\n- `internal/webui/api_chat.go` now holds `gateway.ChatContract`; direct\n `SessionStore`, `Router`, and `TurnHistory` access is historical.\n- The third coupling is closed. UI extraction shipped (`archie-core-8cda.5`,\n closed 2026-09-11): `cmd/archie-ui` serves the dashboard against remote\n Gateway and State Store contracts, holds Line truncated
"body": "# Service decomposition -- decision\n\n**Status:** Draft\n**Date:** 2026-09-05\n**Beads epic:** archie-core-8cda\n**Prior art:** `docs/inspiration/2026-09-05-awx-service-decomposition-and-ansible-task-model.md`,\n`docs/inspiration/module-reference-awx-decomposition-vs-archie.md`,\n`docs/inspiration/service-discovery-research-2026-09-05.md`,\n`/work/artefacts/archie-core-current-state-archify.html`,\n`/work/artefacts/archie-core-ideal-state-archify.html`\n\nThe Phase 3 UI boundary and configuration decision is ratified in\n[`ui-service-boundary.md`](/dev/prds/ui-service-boundary/). That focused document is\nthe implementation authority for `archie-core-8cda.5.2`; this parent remains\nthe broader service-distribution proposal.\n\n## Decision\n\narchie-core moves from one Go binary (`archied`) hosting every domain\nin-process to a set of independently deployable services, each exposing\nexactly one typed contract. Consumers depend on the contract; they never\nreach into another service's internal types, session state, or config.\ngRPC is the synchronous transport; NATS remains for asynchronous fan-out\n(status, telemetry) rather than being replaced.\n\nThis is a **distribution decision**, not a rewrite of Archie's domain\nmodel. The six-domain split already approved in\n`docs/architecture/index.md` and `docs/architecture/organisation.md`\n(Identity, Agent, Messaging, Workflow, Work Intake, Plugin) is unchanged;\nthis PRD is about how the *processes* running that domain logic get\npackaged, contracted, and discovered -- not about redrawing domain\nboundaries.\n\n### Target services\n\n| Service | Contract it owns | Existing code it replaces/wraps |\n|---|---|---|\n| UI Service | thin client only; talks to Gateway and State Store contracts | `internal/webui` (SPA hosting stays; API surface becomes typed contract clients, not a peer with direct access) |\n| Gateway Service | routing / turn / session contract | `internal/gateway` |\n| Messaging Service | channel-plugin contract (Telegram, email, Discord, Teams, ...) | `internal/channels` |\n| Curator Service | curator contract; **optional**, installs as a Gateway plugin | `internal/domain/curator` |\n| Scheduler Service | cron/ticker contract | `internal/domain/scheduling` |\n| Execution Environment | execution-dispatch contract | `internal/domain/workflow`, task dispatch paths |\n| Runner | isolated worktree/container execution | `internal/container`, `internal/agentexec`, `internal/worktree` |\n| State Store | state-access contract | `internal/store` |\n\n### Discovery\n\nPer `docs/inspiration/service-discovery-research-2026-09-05.md`:\n\n- **Primary:** Kubernetes-native discovery (Service + headless-Service/DNS\n + EndpointSlice, served by CoreDNS), delivered as a Helm chart + Operator,\n on k3s for single-host installs and a real cluster for multi-host or a\n hosted offering.\n- **Fallback:** NATS-based discovery (micro `$SRV` announce + JetStream KV\n registry) for no-K8s single-host installs, with a custom gRPC resolver\n reading `host:port` from the KV bucket.\n- Both implementations sit behind one internal interface:\n\n ```go\n type ServiceRegistry interface {\n Resolve(service string) []Endpoint\n Watch(service string) \u003c-chan Event // join/leave\n }\n ```\n\n- An optional service (Curator; others later) that is not installed\n must resolve to a distinct `NotInstalled` outcome, never a `Down`/\n `Unhealthy` one. Under K8s this falls out of DNS returning no record;\n under the NATS fallback it requires an explicit \"installed\" marker in the\n KV registry, not just absence-implies-down.\n\n### Distribution model this supports\n\nBoth self-hosted (customer runs the Helm chart or the NATS-fallback\nbinaries themselves) and a managed/hosted offering (we run the same Helm\nchart) are in scope -- this is the RHEL / Ansible Automation Platform\nmodel: one architecture, sold both ways. This PRD does not decide the\nbusiness model; it decides that the architecture must not foreclose\neither shape.\n\n## Why this shape\n\n`docs/inspiration/module-reference-awx-decomposition-vs-archie.md`\nestablished that Archie's existing domain split already does what AWX's\nservice-decomposition post argues for -- boundaries exist. What didn't\nexist was deployability: `internal/webui` was not a passive frontend. The\nre-baselined coupling inventory is below, and the ratified boundary is\n[`ui-service-boundary.md`](/dev/prds/ui-service-boundary/).\n\n- Telegram task actions now call Gateway's `ChatContract` directly through\n `chatTaskActorAdapter`; the old Telegram-to-webui HTTP detour is historical.\n- `internal/webui/api_chat.go` now holds `gateway.ChatContract`; direct\n `SessionStore`, `Router`, and `TurnHistory` access is historical.\n- The third coupling is closed. UI extraction shipped (`archie-core-8cda.5`,\n closed 2026-09-11): `cmd/archie-ui` serves the dashboard against remote\n Gateway and State Store contracts, holds Line truncated
},
{
"url": "/dev/prds/service-registry/",
@@ -408,6 +414,12 @@
"section": "PRDs",
"body": "# Per-run task detail: attempts, stages, changes, config, debug\n\n**Status:** Approved\n**Authority:** the surface contract itself is\n`docs/architecture/observability.md`.\n**Date:** 2026-09-18\n**Compounds with:** `docs/prds/task-logs-pagination.md` (a bounded read says\nwhat it does not show), `docs/prds/status-health-surface.md` (no surface that\nanswers something already answered elsewhere).\n\n## Decision\n\nA task gets one detail page that answers \"what did this run actually do?\" per\n**attempt**: an ordered stage rail, the change each commit/push produced, the\neffective configuration the attempt ran under, the attempt's log, and the raw\nrecord behind all of it.\n\nThe single organising idea is **attempt attribution**. The dashboard\nrenders a task's whole event stream as one flat timeline, so a retried task\nreads as one long run with two of everything. Every new panel is scoped to one\nattempt and says which one.\n\nThe second organising idea is **provenance, not re-derivation**. What a run\nproduced is captured at the producer, while the evidence exists, and persisted\ndurably. Nothing in this surface tries to reconstruct a past run from state\nthat has since moved on.\n\n## The requirement set\n\n| # | Requirement | Mechanism |\n| --- | --- | --- |\n| R1 | Per-attempt stage rail: stages with name, start, duration, terminal status and error, ordered within one attempt | `GET /api/tasks/{id}/attempts` reads the task's events and groups them by `attempt` |\n| R2 | Events carry an attempt, migrated safely and carried on the wire | `events.attempt` column + presence-gated migrator arm; `Event.attempt = 11` |\n| R3 | Changed files captured at commit/push, persisted per task, exposed, shown with repo/PR links | `changes_captured` durable event written by the commit/push steps; `GET /api/tasks/{id}/changes` |\n| R4 | The effective configuration an attempt ran under, secrets redacted, shown | `config_captured` durable event written once per attempt; read from the events response the page already holds |\n| R5 | Log pane filters by attempt, stage and level; absence stays distinct from an unreadable deployment | `logging.Query.Stage` + `ReadTaskLogRequest.stage = 9`; the pane keeps `disabled` and `found=false` apart |\n| R6 | Retry is reachable from the run view and produces a new attempt shown as a new run | Existing retry action, labelled as a NEW run whose confirm states the previous attempt's commits are discarded |\n| R7 | Raw JSON of the task record and its events for the selected attempt | `GET /api/tasks/{id}/debug` |\n| R8 | Deep-linkable, reload-safe per-task detail page that keeps existing URLs working | `/tasks/{id}` route beside the existing `/tasks?task=N` and `/tasks?status=...` |\n| R9 | Design polish: hierarchy, tokens, both themes, responsive rail, a11y, loading/empty/error states | UI lane; measured at 480px and 700px in both themes |\n| R10 | Documentation of record | This document plus `docs/architecture/observability.md` |\n| R11 | Red-first tests for every new behaviour, full gate, `task ui`, forced `go build ./...`, `go test -race` on touched packages | Per lane; the anti-cost-cutting requirement lives here |\n\n## Attempt attribution: a column, not a guess\n\n`events.Event.Attempt`, persisted by `internal/store` as the `events.attempt`\ncolumn (`internal/store/events.go`, `eventsSchema`), is a real column,\n`NOT NULL DEFAULT 0`. It was chosen over segmenting the stream on `task_queued` /\n`task_retried` because a fold would have to guess which side of a boundary an\nevent belongs to when the daemon restarts mid-attempt, when `RecoverStale`\nrequeues, or when two attempts interleave across a crash. A guess rendered as\nstructure is exactly the false fidelity this surface exists to avoid; a column\nis durable, queryable and ordered by construction.\n\n**`0` means \"not attributable\".** It is every row written before this change\nplus the deliberately task-agnostic producers. It is not an attempt number and\nis never rendered as one. The attempts endpoint reports the count of\nunattributed events so the page can say so instead of presenting old history as\nattempt 1.\n\n## Migration against an existing `archie.db`\n\nThe store's migrator (`migrateTasks` in `internal/store/store.go`) already reads\n`PRAGMA table_info` through `tableColumns` and applies a presence-gated\n`ALTER TABLE ... ADD COLUMN` list. This change adds an `events` arm: a\n`tableColumns(ctx, tx, \"events\")` read beside the other two, and the entry\n`ALTER TABLE events ADD COLUMN attempt INTEGER NOT NULL DEFAULT 0`.\n\nThree consequences a future maintainer must not get wrong:\n\n- `eventsSchema` is `CREATE TABLE IF NOT EXISTS` (`internal/store/events.go`),\n so on an existing database it is a **no-op**. The migrator arm is the only\n thing that adds the column there. This is why the red test builds a raw\n SQLite file with the pre-change `events` DDL and must fail before the arm\n exists: eveLine truncated
},
{
"url": "/dev/prds/task-run-master-detail/",
"title": "Task run detail as a master-detail split pane",
"section": "PRDs",
"body": "# Task run detail as a master-detail split pane\n\n**Status:** Approved\n**Authority:** the panel contracts stay as ratified in\n`docs/prds/task-run-detail.md`; this document changes only the run page's\narrangement of them.\n**Compounds with:** `docs/prds/task-run-detail.md` (attempt attribution, the\nlog stage filter, the per-panel honesty rules).\n\n## Decision\n\nThe run page's five tabs become two panes. The stage rail is the **master**,\nalways visible on the left. The four context panels — log, changed files,\nconfiguration, debug — are the **inspector** on the right, and their tab bar\nmoves into the inspector. The \"Stages\" tab stops existing.\n\nSelecting a stage switches the inspector to the log tab and sets the log\npane's stage filter to that stage. Changing the filter afterwards is the\noperator's choice and is not overridden; rail selection never touches the\nlevel filter. Clicking the selected stage again returns the filter to all\nstages. A stage with no name is rendered but not selectable.\n\nSwitching attempts resets the stage filter to all stages: a selection was\ncommanded on the attempt it was made on, and a different attempt presents a\ndifferent stage list. Changed files, configuration and debug stay\nattempt-scoped; a stage selection never scopes them.\n\n## What does not change\n\n- No new endpoint, RPC, table or configuration field. Every read is one the\n page already makes.\n- The URL contract: `tab` and `attempt` ride in the query string and survive\n a reload. Log filters are not part of the URL; a reload returns the log to\n all stages. `tab=stages` stays a valid URL and renders the log tab; the\n page never generates it again.\n- Attempt attribution, the log stage filter's coverage limit and every\n honesty rule in `task-run-detail.md` still apply: each pane states what it\n cannot show under that document's rendering rules.\n- The task header and the attempt selector sit above both panes.\n\n## Arrangement\n\n- Left pane: fixed-width rail (20rem) with the attempt's stage rows. Status,\n duration, error, the stage's agent report, the attempt's status badge and\n start time, and the attempt-attribution footnotes render in the rail.\n- Right pane: the inspector's tab bar plus the selected panel, filling the\n remaining width.\n- Below the shell's 900px frame breakpoint the rail stacks above the\n inspector; neither pane is hidden.\n- Keyboard: the rail keeps its list semantics and each stage row is a real\n button, so selection and deselection work without a pointer; the inspector\n keeps the WAI-ARIA tabs pattern the tab bar already provides.\n\n## Acceptance\n\n1. The rail is visible without opening any tab, and no \"Stages\" trigger exists.\n2. Clicking a stage opens the log filtered to that stage; clicking it again\n shows all stages.\n3. After a stage selection, a filter change made by the operator is kept, and\n the level filter survives the selection.\n4. Switching attempts resets the stage filter to all stages, and no rail row\n on the new attempt renders as selected unless the operator selected it\n there.\n5. `tab=stages` loads and renders the log tab.\n6. Every inspector tab and attempt deep-link survives a reload.\n7. A stage is selectable and deselectable by keyboard, and the selection\n mirrors the log pane's stage filter.\n8. Below 900px the rail stacks above the inspector.\n9. `task check` passes clean and `ui/dist` matches the sources."
},
{
"url": "/dev/prds/ui-service-boundary/",
"title": "UI Service boundary and configuration ownership",
@@ -424,7 +436,7 @@
"url": "/dev/prds/webhook-intake-security/",
"title": "Webhook intake security -- decision",
"section": "PRDs",
"body": "# Webhook intake security -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-t2db.5`, blocks `archie-core-t2db.4`\n\n## Why this is decided ahead of the code it constrains\n\n`archie-core-t2db` (no-code playbooks) and `archie-core-7d5u` (typed event\nsources) both land a public intake surface whose eventual output is an agent\nwith tool access and a repo. Neither capture (`t2db.1`) nor the intake family\n(`7d5u.3`) has shipped yet, so this decision exists to be a contract the two\nepics build against, not a retrofit once the surface exists. A webhook URL\nthat can start an agent is remote code execution with extra steps if any of\nthe five points below is missing on day one.\n\n## 1. Per-source authentication\n\nReuse the per-route HMAC-SHA256 scheme already in\n`internal/channels/webhook/webhook.go` (`validateHMAC`), unchanged: a source\nregisters with a shared secret; the signature is checked against the raw\nbody. Do not invent a second scheme for intake.\n\n**Capture and triggering split at the signature, not at a separate flag.** An\nevent with a missing or invalid signature is still captured (visible in the\ninspector, marked unauthenticated) so an operator can diagnose a\nmisconfigured sender -- but an unauthenticated event can never be matched\nagainst a binding. Authentication is what promotes an event from \"something\narrived\" to \"something that can run a workflow.\"\n\n## 2. Human approval before a binding arms\n\nA binding has three states: `draft -\u003e pending_approval -\u003e armed`. Only\n`armed` bindings are evaluated against incoming events. Creating or editing a\nbinding's matcher, mapping, or target workflow always sets it to\n`pending_approval`, including edits to an already-armed binding -- an edit is\nnot silently re-armed, or the approval gate is decorative. Approval requires\nan authenticated dashboard session; there is no unattended approval path.\n\nModel: `internal/channels/telegram`'s dangerous-command approval flow\n(`dangerousAction` / `pendingApproval` in `dangerous.go` / `approval.go`) is\nthe existing precedent for \"a human decision gates code from running\" in this\ncodebase -- follow its shape rather than designing a new approval primitive.\n\n## 3. Rate and volume limits, per source\n\nA token-bucket limiter keyed by source ID, not global -- one noisy or hostile\nsender must not exhaust another source's capture budget. Precedent for\nper-key volume capping: `internal/pairing/store.go`'s `MaxPendingPerPlatform`.\n\nOn limit exceeded, the request is rejected (HTTP 429), not silently dropped.\nA silently dropped event is indistinguishable from a sender that never fired\n-- the same invisible-failure shape the update-verification work\n(`archie-core-522`) exists to prevent. The rejection itself is observable in\nthe inspector as a distinct outcome from \"not received.\"\n\n## 4. Blast radius bounded by code, not by prompt wording\n\nA playbook-triggered task runs through exactly the same enforcement as every\nother task: the `[[repos.gate]]` quality gate, `diff_cap_lines`, the\nsandboxed per-task container (`internal/container`), worktree isolation, and\n\"the model never runs git.\" No new relaxation is introduced for\nplaybook-triggered work, and none is needed -- the existing constraints are\nthe control.\n\nMapped payload fields are treated as ordinary user-controlled text inside an\nagent prompt, exactly like an inbound chat message never as trusted\ninstructions. \"The agent should ignore instructions in the payload\" is not a\ncontrol and must not appear as one anywhere in this feature -- per\n`ARCHITECTURE.md`'s environmental-enforcement-over-prompt-rules principle,\nthe boundary is the gate and the sandbox, not a sentence in the system\nprompt.\n\n## 5. Retention and redaction of captured payloads\n\n**Retention:** captured events (bound or not) are purged after 7 days,\nconfigurable per deployment. Unbound events exist to be mapped against; nothing\njustifies keeping them indefinitely once that window has passed, and an\nunbounded capture store is the same disk-exhaustion risk item 3 addresses at\nthe request-rate level.\n\n**Redaction:** before a captured payload is persisted, apply the same\nkey-name heuristic `internal/gateway/stream.go`'s `sensitiveParameterKey`\nalready uses for tool-call parameters (matches `token`, `secret`, `password`,\n`passwd`, `api_key`, `apikey`, `authorization`, `credential`, `cookie`,\n`private_key` against normalized JSON keys) and replace matching values with\nthe same `[redacted]` marker. This is best-effort, not a guarantee -- a\nsender that names a secret field something the heuristic misses will still\nhave it captured. Document that limitation where captured payloads are\ndisplayed, rather than implying the redaction is complete.\n\n**Visibility:** captured payloads, redacted or not, are visible only to an\nauthenticated dashboard operator -- the same authorization bounLine truncated
"body": "# Webhook intake security -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-t2db.5`, blocks `archie-core-t2db.4`\n\n## Why this is decided ahead of the code it constrains\n\n`archie-core-t2db` (no-code playbooks) and `archie-core-7d5u` (typed event\nsources) both land a public intake surface whose eventual output is an agent\nwith tool access and a repo. Neither capture (`t2db.1`) nor the intake family\n(`7d5u.3`) has shipped yet, so this decision exists to be a contract the two\nepics build against, not a retrofit once the surface exists. A webhook URL\nthat can start an agent is remote code execution with extra steps if any of\nthe five points below is missing on day one.\n\n## 1. Per-source authentication\n\nReuse the per-route HMAC-SHA256 scheme already in\n`internal/channels/webhook/webhook.go` (`validateHMAC`), unchanged: a source\nregisters with a shared secret; the signature is checked against the raw\nbody. Do not invent a second scheme for intake.\n\n**Capture and triggering split at the signature, not at a separate flag.** An\nevent with a missing or invalid signature is still captured (visible in the\ninspector, marked unauthenticated) so an operator can diagnose a\nmisconfigured sender -- but an unauthenticated event can never be matched\nagainst a binding. Authentication is what promotes an event from \"something\narrived\" to \"something that can run a workflow.\"\n\n## 2. Human approval before a binding arms\n\nA binding has three states: `draft -\u003e pending_approval -\u003e armed`. Only\n`armed` bindings are evaluated against incoming events. Creating or editing a\nbinding's matcher, mapping, or target workflow always sets it to\n`pending_approval`, including edits to an already-armed binding -- an edit is\nnot silently re-armed, or the approval gate is decorative. Approval requires\nan authenticated dashboard session; there is no unattended approval path.\n\nModel: `internal/channels/telegram`'s dangerous-command approval flow\n(`dangerousAction` / `pendingApproval` in `dangerous.go` / `approval.go`) is\nthe existing precedent for \"a human decision gates code from running\" in this\ncodebase -- follow its shape rather than designing a new approval primitive.\n\n## 3. Rate and volume limits, per source\n\nA token-bucket limiter keyed by source ID, not global -- one noisy or hostile\nsender must not exhaust another source's capture budget. Precedent for\nper-key volume capping: `internal/pairing/store.go`'s `MaxPendingPerPlatform`.\n\nOn limit exceeded, the request is rejected (HTTP 429), not silently dropped.\nA silently dropped event is indistinguishable from a sender that never fired\n-- the same invisible-failure shape the update-verification work\n(`archie-core-522`) exists to prevent. The rejection itself is observable in\nthe inspector as a distinct outcome from \"not received.\"\n\n## 4. Blast radius bounded by code, not by prompt wording\n\nA playbook-triggered task runs through exactly the same enforcement as every\nother task: the `[[repos.gate]]` quality gate, `diff_cap_lines`, the\nsandboxed per-task container (`internal/container`), worktree isolation, and\n\"the model never runs git.\" No new relaxation is introduced for\nplaybook-triggered work, and none is needed -- the existing constraints are\nthe control.\n\nMapped payload fields are treated as ordinary user-controlled text inside an\nagent prompt, exactly like an inbound chat message never as trusted\ninstructions. \"The agent should ignore instructions in the payload\" is not a\ncontrol and must not appear as one anywhere in this feature -- per the\nenvironmental-enforcement principle (`docs/architecture/agent-system.md`,\n\"Existing invariants to preserve\"), the boundary is the gate and the sandbox,\nnot a sentence in the system prompt.\n\n## 5. Retention and redaction of captured payloads\n\n**Retention:** captured events (bound or not) are purged after 7 days,\nconfigurable per deployment. Unbound events exist to be mapped against; nothing\njustifies keeping them indefinitely once that window has passed, and an\nunbounded capture store is the same disk-exhaustion risk item 3 addresses at\nthe request-rate level.\n\n**Redaction:** before a captured payload is persisted, apply the same\nkey-name heuristic `internal/gateway/stream.go`'s `sensitiveParameterKey`\nalready uses for tool-call parameters (matches `token`, `secret`, `password`,\n`passwd`, `api_key`, `apikey`, `authorization`, `credential`, `cookie`,\n`private_key` against normalized JSON keys) and replace matching values with\nthe same `[redacted]` marker. This is best-effort, not a guarantee -- a\nsender that names a secret field something the heuristic misses will still\nhave it captured. Document that limitation where captured payloads are\ndisplayed, rather than implying the redaction is complete.\n\n**Visibility:** captured payloads, redacted or not, are visible only to an\nauthenticated dashboarLine truncated
}
],
"nav": [
@@ -517,6 +529,10 @@
"title": "Agent2Agent as archie's agent-to-agent protocol — decision",
"url": "/dev/prds/agent2agent-protocol/"
},
{
"title": "Artifact sender",
"url": "/dev/prds/artifact-sender/"
},
{
"title": "Binding secret at-rest encryption -- decision",
"url": "/dev/prds/binding-secret-encryption/"
@@ -705,6 +721,10 @@
"title": "Per-run task detail: attempts, stages, changes, config, debug",
"url": "/dev/prds/task-run-detail/"
},
{
"title": "Task run detail as a master-detail split pane",
"url": "/dev/prds/task-run-master-detail/"
},
{
"title": "UI Service boundary and configuration ownership",
"url": "/dev/prds/ui-service-boundary/"
+1 -1
View File
@@ -10,7 +10,7 @@
"url": "/docs/guides/first-playbook/",
"title": "Building your first playbook binding",
"section": "Guides",
"body": "# Building your first playbook binding\n\nThis walks through the whole no-code path the event-capture epic promises:\npoint an external app's webhook at archie, see the real payload it sends,\nmap the fields you care about, bind them to a workflow, and watch the next\nmatching event turn into a task -- no code, no redeploy, no restart. See\n`docs/architecture/bindings.md` for the model and threat model behind each\nstep below.\n\n## 1. Send a test event\n\nPoint whatever external app you want archie to react to at:\n\n```\nPOST http://\u003cyour-archied-host\u003e:8484/webhooks/capture/\u003csource\u003e\n```\n\n`\u003csource\u003e` is a name you choose for this sender (e.g. `sentry`, `github-ci`,\n`stripe`) -- it's just a URL path segment, not a preset list. Send one real\nevent however is easiest for a first test, e.g.:\n\n```bash\ncurl -X POST http://localhost:8484/webhooks/capture/sentry \\\n -H \"Content-Type: application/json\" \\\n -d '{\"issue\": {\"title\": \"NullPointerException in checkout\"}, \"level\": \"error\"}'\n```\n\nThis event isn't signed yet, so it's captured but marked **unauthenticated**\n-- visible for you to design against, but incapable of triggering anything\n(`docs/architecture/bindings.md`'s threat-model section explains why: an\nunauthenticated event can never match a binding, no matter how it looks).\n\n## 2. Inspect the captured payload\n\nOpen the dashboard's **Event inspector** (`/captures`). Your test event\nappears there with its real body -- this is schema-by-example: you're\nlooking at an actual payload from the actual sender, not guessing at a\nschema in advance.\n\n## 3. Map the fields you care about\n\nOpen **Field mappings** (`/mappings`) → **New mapping**. Pick your captured\nevent from the dropdown, then click through its payload tree on the right --\nevery key and value is clickable. Clicking a value binds it as a field\n(name, JSON path, and an inferred type you can change). Add whichever fields\nyour workflow needs (e.g. the issue title), mark the ones that must be\npresent as **Required**, hit **Preview** to confirm they resolve correctly\nagainst the real payload, then **Save**.\n\n## 4. Create the binding\n\nOpen **Playbook bindings** (`/bindings`) → **New binding**:\n\n- **Name** -- anything descriptive.\n- **Source** -- the same `\u003csource\u003e` segment from step 1 (e.g. `sentry`).\n- **Field mapping** -- the one you just saved.\n- **Workflow** -- which registered workflow should run on a match.\n- **Repo pin** (optional) -- leave both blank to use the single configured\n repo; set owner/repo explicitly if you run a multi-repo deployment.\n- **Shared secret** -- a real secret (16+ bytes), never `test1234`. The\n sender signs every request body with this via HMAC-SHA256 so archie can\n tell a genuine event from anyone who finds the URL.\n\nSave. The binding starts in **draft** -- nothing fires yet.\n\n## 5. Approve it\n\nA **draft** or freshly-**edited** binding needs an explicit human approval\nbefore it can ever match a live event -- this is deliberate, not a missing\nstep: an operator authoring a binding is a considered act, an event arriving\nis not, and nothing should self-arm (`docs/architecture/bindings.md`'s\nthreat-model section, point 2). Click **Approve**. Status becomes **armed**.\n\n## 6. Fire it for real\n\nSend the same kind of event again, this time **signed** with the binding's\nsecret:\n\n```bash\nBODY='{\"issue\": {\"title\": \"NullPointerException in checkout\"}, \"level\": \"error\"}'\nSECRET=\"the-secret-you-set-in-step-4\"\nSIG=$(printf '%s' \"$BODY\" | openssl dgst -sha256 -hmac \"$SECRET\" | sed 's/^.* //')\n\ncurl -X POST http://localhost:8484/webhooks/capture/sentry \\\n -H \"Content-Type: application/json\" \\\n -H \"X-Hub-Signature-256: sha256=$SIG\" \\\n -d \"$BODY\"\n```\n\nThis event is captured as **authenticated**, matched against your armed\nbinding, and dispatched into a new task through the exact same\ngate/worktree/sandbox pipeline every other task goes through -- see\n`ARCHITECTURE.md`'s Task Lifecycle section, \"Provenance by origin.\" Check\nthe **Tasks** page; a new task should appear, its body built from the fields\nyour mapping resolved.\n\n## Editing a live binding\n\nAny edit to an armed binding -- even a typo fix -- drops it back to\n**pending_approval** automatically. This can't be bypassed by editing; it\nhas to be re-approved. When editing, leave the **Shared secret** field blank\nto keep the existing secret; only fill it in if you're deliberately\nrotating it.\n"
"body": "# Building your first playbook binding\n\nThis walks through the whole no-code path the event-capture epic promises:\npoint an external app's webhook at archie, see the real payload it sends,\nmap the fields you care about, bind them to a workflow, and watch the next\nmatching event turn into a task -- no code, no redeploy, no restart. See\n`docs/architecture/bindings.md` for the model and threat model behind each\nstep below.\n\n## 1. Send a test event\n\nPoint whatever external app you want archie to react to at:\n\n```\nPOST http://\u003cyour-archied-host\u003e:8484/webhooks/capture/\u003csource\u003e\n```\n\n`\u003csource\u003e` is a name you choose for this sender (e.g. `sentry`, `github-ci`,\n`stripe`) -- it's just a URL path segment, not a preset list. Send one real\nevent however is easiest for a first test, e.g.:\n\n```bash\ncurl -X POST http://localhost:8484/webhooks/capture/sentry \\\n -H \"Content-Type: application/json\" \\\n -d '{\"issue\": {\"title\": \"NullPointerException in checkout\"}, \"level\": \"error\"}'\n```\n\nThis event isn't signed yet, so it's captured but marked **unauthenticated**\n-- visible for you to design against, but incapable of triggering anything\n(`docs/architecture/bindings.md`'s threat-model section explains why: an\nunauthenticated event can never match a binding, no matter how it looks).\n\n## 2. Inspect the captured payload\n\nOpen the dashboard's **Event inspector** (`/captures`). Your test event\nappears there with its real body -- this is schema-by-example: you're\nlooking at an actual payload from the actual sender, not guessing at a\nschema in advance.\n\n## 3. Map the fields you care about\n\nOpen **Field mappings** (`/mappings`) → **New mapping**. Pick your captured\nevent from the dropdown, then click through its payload tree on the right --\nevery key and value is clickable. Clicking a value binds it as a field\n(name, JSON path, and an inferred type you can change). Add whichever fields\nyour workflow needs (e.g. the issue title), mark the ones that must be\npresent as **Required**, hit **Preview** to confirm they resolve correctly\nagainst the real payload, then **Save**.\n\n## 4. Create the binding\n\nOpen **Playbook bindings** (`/bindings`) → **New binding**:\n\n- **Name** -- anything descriptive.\n- **Source** -- the same `\u003csource\u003e` segment from step 1 (e.g. `sentry`).\n- **Field mapping** -- the one you just saved.\n- **Workflow** -- which registered workflow should run on a match.\n- **Repo pin** (optional) -- leave both blank to use the single configured\n repo; set owner/repo explicitly if you run a multi-repo deployment.\n- **Shared secret** -- a real secret (16+ bytes), never `test1234`. The\n sender signs every request body with this via HMAC-SHA256 so archie can\n tell a genuine event from anyone who finds the URL.\n\nSave. The binding starts in **draft** -- nothing fires yet.\n\n## 5. Approve it\n\nA **draft** or freshly-**edited** binding needs an explicit human approval\nbefore it can ever match a live event -- this is deliberate, not a missing\nstep: an operator authoring a binding is a considered act, an event arriving\nis not, and nothing should self-arm (`docs/architecture/bindings.md`'s\nthreat-model section, point 2). Click **Approve**. Status becomes **armed**.\n\n## 6. Fire it for real\n\nSend the same kind of event again, this time **signed** with the binding's\nsecret:\n\n```bash\nBODY='{\"issue\": {\"title\": \"NullPointerException in checkout\"}, \"level\": \"error\"}'\nSECRET=\"the-secret-you-set-in-step-4\"\nSIG=$(printf '%s' \"$BODY\" | openssl dgst -sha256 -hmac \"$SECRET\" | sed 's/^.* //')\n\ncurl -X POST http://localhost:8484/webhooks/capture/sentry \\\n -H \"Content-Type: application/json\" \\\n -H \"X-Hub-Signature-256: sha256=$SIG\" \\\n -d \"$BODY\"\n```\n\nThis event is captured as **authenticated**, matched against your armed\nbinding, and dispatched into a new task through the exact same\ngate/worktree/sandbox pipeline every other task goes through -- see\n`docs/architecture/messaging-and-work-intake.md`'s \"Intake provenance\". Check\nthe **Tasks** page; a new task should appear, its body built from the fields\nyour mapping resolved.\n\n## Editing a live binding\n\nAny edit to an armed binding -- even a typo fix -- drops it back to\n**pending_approval** automatically. This can't be bypassed by editing; it\nhas to be re-approved. When editing, leave the **Shared secret** field blank\nto keep the existing secret; only fill it in if you're deliberately\nrotating it.\n"
}
],
"nav": [
+1 -1
View File
@@ -90,7 +90,7 @@ curl -X POST http://localhost:8484/webhooks/capture/sentry \
This event is captured as **authenticated**, matched against your armed
binding, and dispatched into a new task through the exact same
gate/worktree/sandbox pipeline every other task goes through -- see
`ARCHITECTURE.md`'s Task Lifecycle section, "Provenance by origin." Check
`docs/architecture/messaging-and-work-intake.md`'s "Intake provenance". Check
the **Tasks** page; a new task should appear, its body built from the fields
your mapping resolved.
+81
View File
@@ -0,0 +1,81 @@
# 1.38.0
Released 2026-09-23. [All news](index.md)
### archied — Event capture, mappings and bindings are PocketBase records
- **Captured events, field mappings and playbook bindings live in PocketBase
collections instead of SQLite tables.** They are ordinary records, which is
what lets a binding be changed at runtime rather than by editing a database.
- **A read-only operator surface over the task database ships with the State
Store** (`archie-state-store -admin-addr`). It serves view collections over
tasks, transitions, events, identities and resources, and refuses
`/api/backups` and `POST /api/sql`, so it cannot rewrite state or hand out the
database file.
- **A binding cannot go live without approval.** It moves draft → pending
approval → armed; one binding per source is enforced on insert, on edit and
on approval; and an edit always returns it to pending approval. A secret left
blank on an edit keeps the stored one rather than disarming a live binding.
- **The workspace code-search indexer is gone.** No deployment configured it,
and it was one more resident writer over the workspace.
### archied — Editing a binding or a mapping shows on the activity stream
- **A dashboard edit no longer needs a manual refresh.** A successful binding or
mapping write announces itself on the same activity path a captured event
already uses. The announcement carries the record id and the action and the
dashboard refetches the record, so the signal cannot go stale.
### archied — Cron schedules fire
- **A cron job computes its next run and fires.** Until this release a cron
schedule was accepted at creation and then refused at run time with
`ErrScheduleUnsupported`, so a cron job never ran.
- **The dialect is PocketBase's, and it differs from Vixie cron on one point.**
Day-of-month and day-of-week are combined with AND rather than Vixie's OR, so
`0 0 1 * 1` means Monday the 1st, not "the 1st, or any Monday". The
`@daily`-style macros behave as usual. An expression that can never match,
such as `0 0 30 2 *`, is rejected instead of being left to run forever.
### archied — Tool calls are queryable
- **Every completed tool call is a row in the `tool_calls` collection**, not
only a line in the on-disk task log. The row carries the task, the attempt,
the tool, its result or its error, and when it ran.
- **A failed projection never fails the task.** The event is the record and the
collection is a transcript of it, so a copy that could not be written is
logged and counted rather than propagated.
### archied — A task whose identity no longer resolves parks instead of acting as root
- **A task naming an identity archie no longer knows — renamed, retired or
removed in the control plane — no longer falls back to the root forge's
credential.** It parks with the reason recorded. A task arriving over NATS
with such an identity is refused before it is enqueued. A task with no
identity is the single-identity root path and is unchanged.
### archied — The PR review is published as a readable artifact
- **A completed review is rendered to markdown and published to the
collaborative editor**, so a person reads it and comments on it instead of
reading a wall of text in a pull-request comment.
- **Publishing never fails the review.** With `[artifacts] base_url` unset the
sender is not constructed and publishing is a log line; a publish that fails
is logged with its status and the same review is republished the next time it
completes. Set `[artifacts] token` (or `WORKSPACE_INGEST_TOKEN`) to enable it.
### archied — The activity feed no longer depends on row ids being monotonic
- **The feed's resume cursor is opaque, and a malformed or pre-upgrade cursor
degrades to "from the beginning" rather than failing the stream.** One
consequence on upgrade: a browser holding a cursor issued before this release
replays the backlog once.
### archie-agent
- **The runtime image is rebuilt by this release, and a host must pull it**
(`docker compose pull agent`). The shared State Store contract changed shape
in the sections above — task and event-capture id fields are strings now — and
the two halves are versioned together, so an agent image built before this
release does not speak to the new State Store. There are no agent behaviour
changes of its own in this release.
+25
View File
@@ -0,0 +1,25 @@
# 1.39.0
Released 2026-09-23. [All news](index.md)
### archied
- **Archie now acts on review comments left on its own pull requests.** A
requested-changes review (or a standalone comment) on a PR Archie opened
dispatches a remediation run: the smallest change that satisfies the
feedback, committed to the same PR branch and answered in the review
thread. Approved reviews never remediate, each reaction is its own round,
and the exchange is bounded by the repo's `max_retries` before Archie stops
and says so on the PR.
- **The task run page is a master-detail view.** The run's stage rail and
detail panels sit beside the run list, so one run's timeline is visible
without leaving the page.
- **Live activity groups related updates instead of stacking them by event
kind**, so a burst of progress on one task reads as one story, and the
stage filter resets when you switch attempts.
- Contrast fixes on the info and subtle text tokens clear WCAG AA.
### archie-agent
- The review-reaction remediation path is part of this image; a host that
runs the agent should `docker compose pull agent` to pick it up.
+27
View File
@@ -0,0 +1,27 @@
# 1.40.0
Released 2026-09-23. [All news](index.md)
### archied
- **Every park now says what kind of intervention it needs.** A parked task
is classified as `needs you` (a decision or fix only an operator can
supply), `transient` (an environment problem -- container pool, storage,
transport -- retry once it is fixed), or `terminal` (the repository or
identity cannot act; retrying cannot succeed). The class shows beside the
Parked badge on the dashboard, so "needs you" reads as a request rather
than a failure.
- **Operator retries and review-remediation rounds now have separate
budgets.** An operator's manual retries no longer draw down the rounds
Archie may spend addressing review feedback on its pull requests, and a
round-cap park no longer makes a later retry re-park immediately.
- **`latest` now names the newest release. A push to `main` that is not a
release publishes `edge` and `sha-<commit>` instead. A host that was
following `main` by pulling `latest` stops advancing at this release --
switch it to `edge` to keep tracking `main`, or leave it on `latest` to
follow releases.**
### archie-agent
- The park-classification wire format is part of this image; a host that
runs the agent should `docker compose pull agent` to pick it up.
+6
View File
@@ -2,6 +2,12 @@
Release notes, newest first.
## 2026-09-23
- [1.40.0](1.40.0.md)
- [1.39.0](1.39.0.md)
- [1.38.0](1.38.0.md)
## 2026-09-22
- [1.37.1](1.37.1.md)
+6
View File
@@ -47,8 +47,11 @@
"/news/archie/1.36.0/": "/news/1.36.0/",
"/news/archie/1.37.0/": "/news/1.37.0/",
"/news/archie/1.37.1/": "/news/1.37.1/",
"/news/archie/1.38.0/": "/news/1.38.0/",
"/news/archie/1.39.0/": "/news/1.39.0/",
"/news/archie/1.4.0/": "/news/1.4.0/",
"/news/archie/1.4.1/": "/news/1.4.1/",
"/news/archie/1.40.0/": "/news/1.40.0/",
"/news/archie/1.5.0/": "/news/1.5.0/",
"/news/archie/1.6.0/": "/news/1.6.0/",
"/news/archie/1.7.0/": "/news/1.7.0/",
@@ -113,8 +116,11 @@
"/news/archied/1.36.0/": "/news/1.36.0/",
"/news/archied/1.37.0/": "/news/1.37.0/",
"/news/archied/1.37.1/": "/news/1.37.1/",
"/news/archied/1.38.0/": "/news/1.38.0/",
"/news/archied/1.39.0/": "/news/1.39.0/",
"/news/archied/1.4.0/": "/news/1.4.0/",
"/news/archied/1.4.1/": "/news/1.4.1/",
"/news/archied/1.40.0/": "/news/1.40.0/",
"/news/archied/1.5.0/": "/news/1.5.0/",
"/news/archied/1.6.0/": "/news/1.6.0/",
"/news/archied/1.7.0/": "/news/1.7.0/",
+15
View File
@@ -1,4 +1,19 @@
[
{
"version": "1.40.0",
"date": "2026-09-23",
"body": "### archied\n\n- **Every park now says what kind of intervention it needs.** A parked task\n is classified as `needs you` (a decision or fix only an operator can\n supply), `transient` (an environment problem -- container pool, storage,\n transport -- retry once it is fixed), or `terminal` (the repository or\n identity cannot act; retrying cannot succeed). The class shows beside the\n Parked badge on the dashboard, so \"needs you\" reads as a request rather\n than a failure.\n- **Operator retries and review-remediation rounds now have separate\n budgets.** An operator's manual retries no longer draw down the rounds\n Archie may spend addressing review feedback on its pull requests, and a\n round-cap park no longer makes a later retry re-park immediately.\n- **`latest` now names the newest release. A push to `main` that is not a\n release publishes `edge` and `sha-<commit>` instead. A host that was\n following `main` by pulling `latest` stops advancing at this release --\n switch it to `edge` to keep tracking `main`, or leave it on `latest` to\n follow releases.**\n\n### archie-agent\n\n- The park-classification wire format is part of this image; a host that\n runs the agent should `docker compose pull agent` to pick it up."
},
{
"version": "1.39.0",
"date": "2026-09-23",
"body": "### archied\n\n- **Archie now acts on review comments left on its own pull requests.** A\n requested-changes review (or a standalone comment) on a PR Archie opened\n dispatches a remediation run: the smallest change that satisfies the\n feedback, committed to the same PR branch and answered in the review\n thread. Approved reviews never remediate, each reaction is its own round,\n and the exchange is bounded by the repo's `max_retries` before Archie stops\n and says so on the PR.\n- **The task run page is a master-detail view.** The run's stage rail and\n detail panels sit beside the run list, so one run's timeline is visible\n without leaving the page.\n- **Live activity groups related updates instead of stacking them by event\n kind**, so a burst of progress on one task reads as one story, and the\n stage filter resets when you switch attempts.\n- Contrast fixes on the info and subtle text tokens clear WCAG AA.\n\n### archie-agent\n\n- The review-reaction remediation path is part of this image; a host that\n runs the agent should `docker compose pull agent` to pick it up."
},
{
"version": "1.38.0",
"date": "2026-09-23",
"body": "### archied — Event capture, mappings and bindings are PocketBase records\n\n- **Captured events, field mappings and playbook bindings live in PocketBase\n collections instead of SQLite tables.** They are ordinary records, which is\n what lets a binding be changed at runtime rather than by editing a database.\n- **A read-only operator surface over the task database ships with the State\n Store** (`archie-state-store -admin-addr`). It serves view collections over\n tasks, transitions, events, identities and resources, and refuses\n `/api/backups` and `POST /api/sql`, so it cannot rewrite state or hand out the\n database file.\n- **A binding cannot go live without approval.** It moves draft → pending\n approval → armed; one binding per source is enforced on insert, on edit and\n on approval; and an edit always returns it to pending approval. A secret left\n blank on an edit keeps the stored one rather than disarming a live binding.\n- **The workspace code-search indexer is gone.** No deployment configured it,\n and it was one more resident writer over the workspace.\n\n### archied — Editing a binding or a mapping shows on the activity stream\n\n- **A dashboard edit no longer needs a manual refresh.** A successful binding or\n mapping write announces itself on the same activity path a captured event\n already uses. The announcement carries the record id and the action and the\n dashboard refetches the record, so the signal cannot go stale.\n\n### archied — Cron schedules fire\n\n- **A cron job computes its next run and fires.** Until this release a cron\n schedule was accepted at creation and then refused at run time with\n `ErrScheduleUnsupported`, so a cron job never ran.\n- **The dialect is PocketBase's, and it differs from Vixie cron on one point.**\n Day-of-month and day-of-week are combined with AND rather than Vixie's OR, so\n `0 0 1 * 1` means Monday the 1st, not \"the 1st, or any Monday\". The\n `@daily`-style macros behave as usual. An expression that can never match,\n such as `0 0 30 2 *`, is rejected instead of being left to run forever.\n\n### archied — Tool calls are queryable\n\n- **Every completed tool call is a row in the `tool_calls` collection**, not\n only a line in the on-disk task log. The row carries the task, the attempt,\n the tool, its result or its error, and when it ran.\n- **A failed projection never fails the task.** The event is the record and the\n collection is a transcript of it, so a copy that could not be written is\n logged and counted rather than propagated.\n\n### archied — A task whose identity no longer resolves parks instead of acting as root\n\n- **A task naming an identity archie no longer knows — renamed, retired or\n removed in the control plane — no longer falls back to the root forge's\n credential.** It parks with the reason recorded. A task arriving over NATS\n with such an identity is refused before it is enqueued. A task with no\n identity is the single-identity root path and is unchanged.\n\n### archied — The PR review is published as a readable artifact\n\n- **A completed review is rendered to markdown and published to the\n collaborative editor**, so a person reads it and comments on it instead of\n reading a wall of text in a pull-request comment.\n- **Publishing never fails the review.** With `[artifacts] base_url` unset the\n sender is not constructed and publishing is a log line; a publish that fails\n is logged with its status and the same review is republished the next time it\n completes. Set `[artifacts] token` (or `WORKSPACE_INGEST_TOKEN`) to enable it.\n\n### archied — The activity feed no longer depends on row ids being monotonic\n\n- **The feed's resume cursor is opaque, and a malformed or pre-upgrade cursor\n degrades to \"from the beginning\" rather than failing the stream.** One\n consequence on upgrade: a browser holding a cursor issued before this release\n replays the backlog once.\n\n### archie-agent\n\n- **The runtime image is rebuilt by this release, and a host must pull it**\n (`docker compose pull agent`). The shared State Store contract changed shape\n in the sections above — task and event-capture id fields are strings now — and\n the two halves are versioned together, so an agent image built before this\n release does not speak to the new State Store. There are no agent behaviour\n changes of its own in this release."
},
{
"version": "1.37.1",
"date": "2026-09-22",
+83
View File
@@ -0,0 +1,83 @@
# 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`) with
`token_env` fallback naming `WORKSPACE_INGEST_TOKEN`.
- An empty `base_url` disables 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/artifactsync` exposing 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 — the `crondelivery.Courier` posture.
- The client POSTs the frozen contract body. Each publish sends the complete
source: versions of record are full snapshots, never diffs.
- A `503` response is retried three times with backoff. `401` and `400` are not
retried; they are logged with the field reason the response names.
- `requestId` is `artifact:<task-id>:<version>` when the producer is task-backed,
otherwise `artifact:<identity>:<sentAt-utc>`. Sending the same `requestId` with
an equal or older `sentAt` must be a server-side no-op, which makes sender-side
retry safe.
## Report rendering
- `ReviewReport` gains a pure markdown renderer in `internal/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 as `system:pr-reviewer`
when no task identity resolves; otherwise the task's identity name.
- `source`: the producing subsystem, `pr-review` for 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 `SecretRef` path and the
`token_env` fallback.
+2 -2
View File
@@ -25,7 +25,7 @@ Every claim in this document is mapped to what exists in the tree.
| Tool guardrails (repeat-failure / no-progress) | **Implemented, not on the call path** | `internal/tools/guardrail.go` engine exists. Its only non-test caller is `dispatchOne` — which is itself unreachable — so **the chat path never consults it**, and the agent path only records per *stage* (`domain/workflow/agent.go`) |
| Structured capture tools (model reports into a typed store, not prose) | **Implemented** | `internal/app/agentworker/review.go` `record_finding` / `record_checked` — `core.NewTypedTool` appending to a caller-owned slice. This is the pattern a research source ledger should reuse |
| Curator engine (interval, declared tool set, lifecycle) | **Implemented, tools broken** | `internal/domain/curator`; a curator declaring tools is **refused** at registration (`registry.go`, no `ToolBuilder` implementation) and `curatorLLMRunner` (`internal/app/archied/main.go`) drops `ChatRequest.Tools`. Budgets are time+concurrency only (`runtime.go`) — **no token budget** |
| Cron / scheduling + delivery router | **Implemented, wired into no binary** | `internal/domain/scheduling`, `internal/infrastructure/cronstore` (schema v2, `Kind` discriminator), `internal/infrastructure/crondelivery` — all present and green, but `go list -deps` for every `cmd/` contains none of them, and `cron`-expression firing arithmetic is unimplemented (`schedule.go`, "slice 2"). `ARCHITECTURE.md` still asserts "**No daemon-internal cron.**" |
| Cron / scheduling + delivery router | **Implemented, wired into the daemon** | `internal/domain/scheduling` (ticker engine), `internal/infrastructure/cronstore` (schema v2, `Kind` discriminator), and `internal/infrastructure/crondelivery`; `internal/app/archied/scheduling.go` composes them and `main.go` starts the engine. |
| Workflow engines (multi-stage, resumable) | **Implemented, worktree-bound** | `internal/domain/workflow` — every non-triage workflow opens with `StagePrepareWorktree()` and mounts `tc.Dir` into a container; the task persists after every stage (`workflow.go`). `triage.go` documents there is "no cheaper directory-less classification primitive" |
| Long-running chat-initiated work with progress | **Partial** | Chat turns run **once, synchronously**, inline in the channel's turn runner (`internal/gateway/turn.go`). Chat can spawn a *workflow task* (`task_spawn`) which is asynchronous — but that path is worktree/PR-shaped |
| **Operator-push delivery of an async result** | **Aspirational — zero code** | Nothing pushes a finished result to a chat. No channel subscribes to the event bus (Telegram only *publishes* `KindTurnCompleted`); `crondelivery.Courier` is the intended seam but has **no implementation and no caller**; `send_file` works only inside the live turn. The one out-of-band notification in the tree is feasibility's n8n webhook (`feasibility.go`) |
@@ -198,7 +198,7 @@ Reusing it would mean every ad-hoc research run leaves a permanent job row.
| Collator | `internal/domain/research` | Model pass over `[]ChildConclusion` + source store → report body |
| Report renderer | `internal/domain/research` | Markdown + numbered citation list rendered **from the store** |
| Chat trigger | slice 2: `internal/tools/research`; slice 3: gateway tool + courier in `internal/app/archied` | — |
| Durable run + delivery (slice 3) | `internal/domain/research` + `internal/infrastructure/research` + `internal/app/archied` wiring | Follows the strict plugin-engine rule in `ARCHITECTURE.md` ("Plugin engine
| Durable run + delivery (slice 3) | `internal/domain/research` + `internal/infrastructure/research` + `internal/app/archied` wiring | Follows the strict plugin-engine rule in `docs/architecture/plugins-and-extensions.md` ("Plugin engine
rule (strict)"): typed contract, owning registry with start/health/stop, narrow typed registrar |
### Why not the curator
+2 -1
View File
@@ -42,7 +42,8 @@ long as it's implemented behind one of the typed engine families below.
generic interface -- see "Typed positions, not one generic hook" below,
which is how it stays compliant with the plugin engine rule instead of
reopening that document's #4.
- `ARCHITECTURE.md#plugin-engine-rule-strict` governs every extension point
- `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`
governs every extension point
introduced here. Every position below is a typed domain contract with an
owning registry, not a generic callback map. This is a hard constraint,
confirmed against the existing rule text before writing this doc.
+2 -1
View File
@@ -12,7 +12,8 @@ each question and saying which packages change.
## 1. In-process typed families, not out-of-process dispatch
Archie has no out-of-process extension mechanism. The plugin engine
rule (`ARCHITECTURE.md#plugin-engine-rule-strict`, mechanically checked by
rule (`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`,
mechanically checked by
`internal/plugin/architecture_test.go`) keeps every capability family
in-process behind a narrow typed registrar; NATS RPC exists for
daemon<->agentexec, a different actor with a different trust boundary (task
+3 -2
View File
@@ -25,8 +25,9 @@ in the repo defines this (`grep -ri image` over `internal/domain` and
## Design
Follows the plugin engine family shape already established by
`internal/domain/curator` and `internal/domain/memory` (ARCHITECTURE.md
"plugin engine rule strict"): a typed contract with real domain operations,
`internal/domain/curator` and `internal/domain/memory`
(`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`): a
typed contract with real domain operations,
an owning `Registry` (register/get/names, no start/stop lifecycle — see
below), and narrow host access via a `Registrar`.
+2 -1
View File
@@ -332,7 +332,8 @@ Each step is independently verifiable and lands green on its own.
4. **Chat write path.** The tool adapter onto CRUD and the turn's subject on the
context. *Depends on 3, because a write is only observable through the read.*
5. **Delete `internal/memory` and the dead config/dashboard surface**, and
rewrite `ARCHITECTURE.md`'s "Memory engine family" section to describe the
rewrite the "Memory engine family" section of
`docs/architecture/plugins-and-extensions.md` to describe the
engine family rather than a manager it deleted. *Depends on 3 and 4.*
Steps 3 and 4 are separable from each other; step 1 is separable from everything.
+5
View File
@@ -3,6 +3,11 @@
**Status:** Approved
**Date:** 2026-09-21
**Beads issue:** `archie-core-2ncm.2`
**Superseded in part:** `docs/prds/release-stream-and-commit-rules.md` supersedes the
sections "Source of truth" and "Two components" below. There is now one release
stream: a single `CHANGELOG.md` carries every release section, the per-component
`CHANGELOG.archied.md` and `CHANGELOG.archie.md` are deleted, and one `vX.Y.Z` tag
names a release. The rest of this document still holds.
A public news page and a release-notes page for every version. Both are derived
from the changelogs the release process already produces, so publishing a
+1 -1
View File
@@ -116,7 +116,7 @@ re-baselined coupling inventory is below, and the ratified boundary is
- Any concrete adoption of Pi (or another external agent harness) as an
execution runner. Raised in conversation alongside this decomposition,
but it is a separate decision (agent execution as a strict data
boundary, `ARCHITECTURE.md`) and does not gate or get gated by this PRD.
boundary, `docs/architecture/agent-system.md`) and does not gate or get gated by this PRD.
## Open questions
+69
View File
@@ -0,0 +1,69 @@
# Task run detail as a master-detail split pane
**Status:** Approved
**Authority:** the panel contracts stay as ratified in
`docs/prds/task-run-detail.md`; this document changes only the run page's
arrangement of them.
**Compounds with:** `docs/prds/task-run-detail.md` (attempt attribution, the
log stage filter, the per-panel honesty rules).
## Decision
The run page's five tabs become two panes. The stage rail is the **master**,
always visible on the left. The four context panels — log, changed files,
configuration, debug — are the **inspector** on the right, and their tab bar
moves into the inspector. The "Stages" tab stops existing.
Selecting a stage switches the inspector to the log tab and sets the log
pane's stage filter to that stage. Changing the filter afterwards is the
operator's choice and is not overridden; rail selection never touches the
level filter. Clicking the selected stage again returns the filter to all
stages. A stage with no name is rendered but not selectable.
Switching attempts resets the stage filter to all stages: a selection was
commanded on the attempt it was made on, and a different attempt presents a
different stage list. Changed files, configuration and debug stay
attempt-scoped; a stage selection never scopes them.
## What does not change
- No new endpoint, RPC, table or configuration field. Every read is one the
page already makes.
- The URL contract: `tab` and `attempt` ride in the query string and survive
a reload. Log filters are not part of the URL; a reload returns the log to
all stages. `tab=stages` stays a valid URL and renders the log tab; the
page never generates it again.
- Attempt attribution, the log stage filter's coverage limit and every
honesty rule in `task-run-detail.md` still apply: each pane states what it
cannot show under that document's rendering rules.
- The task header and the attempt selector sit above both panes.
## Arrangement
- Left pane: fixed-width rail (20rem) with the attempt's stage rows. Status,
duration, error, the stage's agent report, the attempt's status badge and
start time, and the attempt-attribution footnotes render in the rail.
- Right pane: the inspector's tab bar plus the selected panel, filling the
remaining width.
- Below the shell's 900px frame breakpoint the rail stacks above the
inspector; neither pane is hidden.
- Keyboard: the rail keeps its list semantics and each stage row is a real
button, so selection and deselection work without a pointer; the inspector
keeps the WAI-ARIA tabs pattern the tab bar already provides.
## Acceptance
1. The rail is visible without opening any tab, and no "Stages" trigger exists.
2. Clicking a stage opens the log filtered to that stage; clicking it again
shows all stages.
3. After a stage selection, a filter change made by the operator is kept, and
the level filter survives the selection.
4. Switching attempts resets the stage filter to all stages, and no rail row
on the new attempt renders as selected unless the operator selected it
there.
5. `tab=stages` loads and renders the log tab.
6. Every inspector tab and attempt deep-link survives a reload.
7. A stage is selectable and deselectable by keyboard, and the selection
mirrors the log pane's stage filter.
8. Below 900px the rail stacks above the inspector.
9. `task check` passes clean and `ui/dist` matches the sources.
+4 -4
View File
@@ -66,10 +66,10 @@ the control.
Mapped payload fields are treated as ordinary user-controlled text inside an
agent prompt, exactly like an inbound chat message never as trusted
instructions. "The agent should ignore instructions in the payload" is not a
control and must not appear as one anywhere in this feature -- per
`ARCHITECTURE.md`'s environmental-enforcement-over-prompt-rules principle,
the boundary is the gate and the sandbox, not a sentence in the system
prompt.
control and must not appear as one anywhere in this feature -- per the
environmental-enforcement principle (`docs/architecture/agent-system.md`,
"Existing invariants to preserve"), the boundary is the gate and the sandbox,
not a sentence in the system prompt.
## 5. Retention and redaction of captured payloads
+18 -3
View File
@@ -9,27 +9,36 @@ require (
github.com/ProtonMail/go-crypto v1.4.1 // indirect
github.com/antithesishq/antithesis-sdk-go v0.8.0 // indirect
github.com/antlr4-go/antlr/v4 v4.13.1 // indirect
github.com/asaskevich/govalidator v0.0.0-20230301143203-a9d515a09cc2 // indirect
github.com/cespare/xxhash/v2 v2.3.0 // indirect
github.com/cloudflare/circl v1.6.5 // indirect
github.com/containerd/errdefs v1.0.0 // indirect
github.com/containerd/errdefs/pkg v0.3.0 // indirect
github.com/davidmz/go-pageant v1.0.2 // indirect
github.com/disintegration/imaging v1.6.2 // indirect
github.com/distribution/reference v0.6.0 // indirect
github.com/docker/go-connections v0.8.1 // indirect
github.com/docker/go-units v0.5.0 // indirect
github.com/domodwyer/mailyak/v3 v3.6.2 // indirect
github.com/dustin/go-humanize v1.1.0 // indirect
github.com/emirpasic/gods v1.18.1 // indirect
github.com/fatih/color v1.19.0 // indirect
github.com/felixge/httpsnoop v1.1.0 // indirect
github.com/fsnotify/fsnotify v1.10.1 // indirect
github.com/gabriel-vasile/mimetype v1.4.15 // indirect
github.com/ganigeorgiev/fexpr v0.6.0 // indirect
github.com/go-fed/httpsig v1.1.0 // indirect
github.com/go-git/gcfg/v2 v2.0.2 // indirect
github.com/go-logr/logr v1.4.4 // indirect
github.com/go-logr/stdr v1.2.2 // indirect
github.com/golang-jwt/jwt/v5 v5.3.1 // indirect
github.com/google/go-querystring v1.2.0 // indirect
github.com/google/go-tpm v0.9.8 // indirect
github.com/hashicorp/go-version v1.9.0 // indirect
github.com/kevinburke/ssh_config v1.6.0 // indirect
github.com/klauspost/compress v1.20.0 // indirect
github.com/klauspost/cpuid/v2 v2.4.0 // indirect
github.com/mattn/go-colorable v0.1.15 // indirect
github.com/mattn/go-isatty v0.0.24 // indirect
github.com/minio/highwayhash v1.0.4 // indirect
github.com/moby/docker-image-spec v1.3.1 // indirect
@@ -41,8 +50,12 @@ require (
github.com/opencontainers/image-spec v1.1.1 // indirect
github.com/pjbgf/sha1cd v0.6.0 // indirect
github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c // indirect
github.com/pocketbase/ozzo-validation/v4 v4.3.0 // indirect
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
github.com/sergi/go-diff v1.4.0 // indirect
github.com/spf13/cast v1.10.0 // indirect
github.com/spf13/cobra v1.10.2 // indirect
github.com/spf13/pflag v1.0.10 // indirect
go.opentelemetry.io/auto/sdk v1.2.1 // indirect
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.71.0 // indirect
go.opentelemetry.io/otel v1.46.0 // indirect
@@ -51,13 +64,14 @@ require (
go.yaml.in/yaml/v3 v3.0.5 // indirect
golang.org/x/crypto v0.57.0 // indirect
golang.org/x/exp v0.0.0-20260908205506-85c1c2202aba // indirect
golang.org/x/image v0.46.0 // indirect
golang.org/x/sync v0.23.0 // indirect
golang.org/x/sys v0.48.0 // indirect
golang.org/x/text v0.42.0 // indirect
golang.org/x/time v0.16.0 // indirect
google.golang.org/genproto/googleapis/api v0.0.0-20260921155816-b14227669459 // indirect
google.golang.org/genproto/googleapis/rpc v0.0.0-20260921155816-b14227669459 // indirect
modernc.org/libc v1.77.1 // indirect
modernc.org/libc v1.74.4 // indirect
modernc.org/mathutil v1.7.1 // indirect
modernc.org/memory v1.12.1 // indirect
)
@@ -71,13 +85,14 @@ require (
github.com/go-git/go-git/v6 v6.0.0-alpha.5
github.com/go-jose/go-jose/v4 v4.1.5
github.com/go-telegram/bot v1.27.0
github.com/google/codesearch v1.3.0-rc.1
github.com/google/go-github/v78 v78.0.0
github.com/google/uuid v1.6.0
github.com/moby/moby/api v1.56.0
github.com/moby/moby/client v0.6.0
github.com/nats-io/nats-server/v2 v2.15.0
github.com/nats-io/nats.go v1.54.0
github.com/pocketbase/dbx v1.12.0
github.com/pocketbase/pocketbase v0.40.4
github.com/samcharles93/ai-sdk v0.1.39
github.com/traefik/yaegi v0.16.1
golang.org/x/net v0.59.0
@@ -86,5 +101,5 @@ require (
google.golang.org/grpc v1.85.0-dev.0.20260825072537-93e31b48545e
google.golang.org/protobuf v1.36.12
gopkg.in/yaml.v3 v3.0.1
modernc.org/sqlite v1.59.0
modernc.org/sqlite v1.57.0
)
+51 -2
View File
@@ -25,6 +25,9 @@ github.com/antlr4-go/antlr/v4 v4.13.1 h1:SqQKkuVZ+zWkMMNkjy5FZe5mr5WURWnlpmOuzYW
github.com/antlr4-go/antlr/v4 v4.13.1/go.mod h1:GKmUxMtwp6ZgGwZSva4eWPC5mS6vUAmOABFgjdkM7Nw=
github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5 h1:0CwZNZbxp69SHPdPJAN/hZIm0C4OItdklCFmMRWYpio=
github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5/go.mod h1:wHh0iHkYZB8zMSxRWpUBQtwG5a7fFgvEO+odwuTv2gs=
github.com/asaskevich/govalidator v0.0.0-20200108200545-475eaeb16496/go.mod h1:oGkLhpf+kjZl6xBf758TQhh5XrAeiJv/7FRz/2spLIg=
github.com/asaskevich/govalidator v0.0.0-20230301143203-a9d515a09cc2 h1:DklsrG3dyBCFEj5IhUbnKptjxatkF07cF2ak3yi77so=
github.com/asaskevich/govalidator v0.0.0-20230301143203-a9d515a09cc2/go.mod h1:WaHUgvxTVq04UNunO+XhnAqY/wQc+bxr74GqbsZ/Jqw=
github.com/bwesterb/go-ristretto v1.2.4/go.mod h1:fUIoIZaG73pV5biE2Blr2xEzDoMj7NFEuV9ekS419A0=
github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
@@ -38,17 +41,22 @@ github.com/containerd/errdefs/pkg v0.3.0/go.mod h1:NJw6s9HwNuRhnjJhM7pylWwMyAkmC
github.com/containerd/typeurl/v2 v2.2.0/go.mod h1:8XOOxnyatxSWuG8OfsZXVnAF4iZfedjS/8UHSPJnX4g=
github.com/coreos/go-oidc/v3 v3.21.0 h1:wZo4Q9Pum8dYEj0eMUPrqR+kvuGkeUplbLpNCkBqoWM=
github.com/coreos/go-oidc/v3 v3.21.0/go.mod h1:DYCf24+ncYi+XkIH97GY1+dqoRlbaSI26KVTCI9SrY4=
github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE=
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/davidmz/go-pageant v1.0.2 h1:bPblRCh5jGU+Uptpz6LgMZGD5hJoOt7otgT454WvHn0=
github.com/davidmz/go-pageant v1.0.2/go.mod h1:P2EDDnMqIwG5Rrp05dTRITj9z2zpGcD9efWSkTNKLIE=
github.com/disintegration/imaging v1.6.2 h1:w1LecBlG2Lnp8B3jk5zSuNqd7b4DXhcjwek1ei82L+c=
github.com/disintegration/imaging v1.6.2/go.mod h1:44/5580QXChDfwIclfc/PCwrr44amcmDAg8hxG0Ewe4=
github.com/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5QvfrDyIgxBk=
github.com/distribution/reference v0.6.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E=
github.com/docker/go-connections v0.8.1 h1:JibmG5hULs5qXSr/cp/w3Pw5fZuStt4MOHMUExb29/M=
github.com/docker/go-connections v0.8.1/go.mod h1:no1qkHdjq7kLMGUXYAduOhYPSJxxvgWBh7ogVvptn3Q=
github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4=
github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk=
github.com/domodwyer/mailyak/v3 v3.6.2 h1:x3tGMsyFhTCaxp6ycgR0FE/bu5QiNp+hetUuCOBXMn8=
github.com/domodwyer/mailyak/v3 v3.6.2/go.mod h1:lOm/u9CyCVWHeaAmHIdF4RiKVxKUT/H5XX10lIKAL6c=
github.com/dustin/go-humanize v1.1.0 h1:dbKTrvD0klcbBV/h4AWJdMuZogJACoMlvWIWZ5b2xWg=
github.com/dustin/go-humanize v1.1.0/go.mod h1:hc1CvRkJMsgxqjmjMQF3QNRAZBwY8AXBAzKYoSX9sFI=
github.com/emirpasic/gods v1.18.1 h1:FXtiHYKDGKCW2KzwZKx0iC0PQmdlorYgdFG9jPXJ1Bc=
@@ -57,8 +65,16 @@ github.com/envoyproxy/go-control-plane v0.14.0/go.mod h1:NcS5X47pLl/hfqxU70yPwL9
github.com/envoyproxy/go-control-plane/envoy v1.39.0/go.mod h1:5e4ylfTZO723MEEFsCpSW4ZEBWR8mwkEyXfwJBTCZ9c=
github.com/envoyproxy/go-control-plane/ratelimit v0.1.0/go.mod h1:Wk+tMFAFbCXaJPzVVHnPgRKdUdwW/KdbRt94AzgRee4=
github.com/envoyproxy/protoc-gen-validate v1.3.3/go.mod h1:TsndJ/ngyIdQRhMcVVGDDHINPLWB7C82oDArY51KfB0=
github.com/fatih/color v1.19.0 h1:Zp3PiM21/9Ld6FzSKyL5c/BULoe/ONr9KlbYVOfG8+w=
github.com/fatih/color v1.19.0/go.mod h1:zNk67I0ZUT1bEGsSGyCZYZNrHuTkJJB+r6Q9VuMi0LE=
github.com/felixge/httpsnoop v1.1.0 h1:3YtUj32ZZkqZtt3sZZsClsymw/QDuVfpNhoA31zeORc=
github.com/felixge/httpsnoop v1.1.0/go.mod h1:Zqxgdd+1Rkcz8euOqdr7lqgCRJztwr5hp9vDSi5UZCE=
github.com/fsnotify/fsnotify v1.10.1 h1:b0/UzAf9yR5rhf3RPm9gf3ehBPpf0oZKIjtpKrx59Ho=
github.com/fsnotify/fsnotify v1.10.1/go.mod h1:TLheqan6HD6GBK6PrDWyDPBaEV8LspOxvPSjC+bVfgo=
github.com/gabriel-vasile/mimetype v1.4.15 h1:05iP/CYtZ/w455R/KZM6rZ5ieAdh99UPtd+d3YzLmaI=
github.com/gabriel-vasile/mimetype v1.4.15/go.mod h1:azpTcoLcDZRNgFou5j+APrqQx9HqVPWa6ijYQIIVswQ=
github.com/ganigeorgiev/fexpr v0.6.0 h1:Fza3O/QMBKEudUvxV862qe6GjxM60GJjjKytdp+VQus=
github.com/ganigeorgiev/fexpr v0.6.0/go.mod h1:RyGiGqmeXhEQ6+mlGdnUleLHgtzzu/VGO2WtJkF5drE=
github.com/gliderlabs/ssh v0.3.8 h1:a4YXD1V7xMF9g5nTkdfnja3Sxy1PVDCj1Zg4Wb8vY6c=
github.com/gliderlabs/ssh v0.3.8/go.mod h1:xYoytBv1sV0aL3CavoDuJIQNURXkkfPA/wxQ1pL1fAU=
github.com/go-fed/httpsig v1.1.0 h1:9M+hb0jkEICD8/cAiNqEB66R87tTINszBRTjwjQzWcI=
@@ -81,14 +97,16 @@ github.com/go-logr/logr v1.4.4/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ4
github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
github.com/go-quicktest/qt v1.101.0/go.mod h1:14Bz/f7NwaXPtdYEgzsx46kqSxVwTbzVZsDC26tQJow=
github.com/go-sql-driver/mysql v1.4.1/go.mod h1:zAC/RDZ24gD3HViQzih4MyKcchzm+sOG5ZlKdlhCg5w=
github.com/go-telegram/bot v1.27.0 h1:PG9yBDzM8O26oUerE9SZwWlHon4RpH8WcNslZ7CEZmE=
github.com/go-telegram/bot v1.27.0/go.mod h1:i2TRs7fXWIeaceF3z7KzsMt/he0TwkVC680mvdTFYeM=
github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY=
github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
github.com/golang/glog v1.2.5/go.mod h1:6AhwSGph0fcJtXVM/PEHPqZlFeoLxhs7/t5UDAwmO+w=
github.com/golang/protobuf v1.3.1/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
github.com/google/codesearch v1.3.0-rc.1 h1:vSFGuF5wS3sjimuLzqPG+PGjWQ9VvEtPFbxdZD7YuuQ=
github.com/google/codesearch v1.3.0-rc.1/go.mod h1:hKdpx7wOsvk2WLT/D6NLPxFeLT8jKCehZu21JpA2rIY=
github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
@@ -110,6 +128,7 @@ github.com/hashicorp/go-version v1.9.0 h1:CeOIz6k+LoN3qX9Z0tyQrPtiB1DFYRPfCIBtaX
github.com/hashicorp/go-version v1.9.0/go.mod h1:fltr4n8CU8Ke44wwGCBoEymUuxUHl09ZGVZPK5anwXA=
github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
github.com/kevinburke/ssh_config v1.6.0 h1:J1FBfmuVosPHf5GRdltRLhPJtJpTlMdKTBjRgTaQBFY=
github.com/kevinburke/ssh_config v1.6.0/go.mod h1:q2RIzfka+BXARoNexmF9gkxEX7DmvbW9P4hIVx2Kg4M=
github.com/klauspost/compress v1.20.0 h1:a3C1ke2ohxFymNlb2HWAHjDeKCI90scRskErZkR0ezA=
@@ -123,6 +142,8 @@ github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
github.com/mattn/go-colorable v0.1.15 h1:+u9SLTRGnXv73cEsnsmoZBom+dMU88B2M0aDcWy0/jY=
github.com/mattn/go-colorable v0.1.15/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
github.com/mattn/go-isatty v0.0.24 h1:tGZZoVgT/KiqK1c8ocVLeDS8BSWMRd47J3Lbz7vsReI=
github.com/mattn/go-isatty v0.0.24/go.mod h1:nMCL3Zebbrt45jsMDgnfIwz6ydEQApk5oEI3HqDio6A=
github.com/minio/highwayhash v1.0.4 h1:asJizugGgchQod2ja9NJlGOWq4s7KsAWr5XUc9Clgl4=
@@ -156,17 +177,31 @@ github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c h1:+mdjkGKdHQG3305AYmd
github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c/go.mod h1:7rwL4CYBLnjLxUqIJNnCWiEdr3bn6IUYi15bNlnbCCU=
github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10/go.mod h1:t/avpk3KcrXxUnYOhZhMXJlSEyie6gQbtLq5NM3loB8=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/pocketbase/dbx v1.12.0 h1:/oLErM+A0b4xI0PWTGPqSDVjzix48PqI/bng2l0PzoA=
github.com/pocketbase/dbx v1.12.0/go.mod h1:xXRCIAKTHMgUCyCKZm55pUOdvFziJjQfXaWKhu2vhMs=
github.com/pocketbase/ozzo-validation/v4 v4.3.0 h1:uKBDVma7bZqgR2a6AwE+k9hkuDFfiZMpBHQdZ1z3iQs=
github.com/pocketbase/ozzo-validation/v4 v4.3.0/go.mod h1:6XNjSTw/Jb2F8LOkKO3oyzIWExbrGiYoS4uVxVwz90g=
github.com/pocketbase/pocketbase v0.40.4 h1:0SvSUreR3NhUMCs9LchE59oEG53efZ3cKiMGyAGBN9U=
github.com/pocketbase/pocketbase v0.40.4/go.mod h1:2mU+80FLiY1fb13WZRg8Xx/lKg4nTjgKVJMigyRH6k0=
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
github.com/russross/blackfriday v1.6.0/go.mod h1:ti0ldHuxg49ri4ksnFxlkCfN+hvslNlmVHqNRXXJNAY=
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
github.com/samcharles93/ai-sdk v0.1.39 h1:gbNPYeA27MifReCruBiqMgb4fFSjCDi1Zv57a9bo0Vo=
github.com/samcharles93/ai-sdk v0.1.39/go.mod h1:u4zrQ9/Q58L5mNEut4bNQ1ks+RCKq71LN5EDz2N/0Zk=
github.com/santhosh-tekuri/jsonschema/v5 v5.3.1/go.mod h1:uToXkOrWAZ6/Oc07xWQrPOhJotwFIyu2bBVN41fcDUY=
github.com/sergi/go-diff v1.4.0 h1:n/SP9D5ad1fORl+llWyN+D6qoUETXNZARKjyY2/KVCw=
github.com/sergi/go-diff v1.4.0/go.mod h1:A0bzQcvG0E7Rwjx0REVgAGH58e96+X0MeOfepqsbeW4=
github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=
github.com/spf13/cast v1.10.0 h1:h2x0u2shc1QuLHfxi+cTJvs30+ZAHOGRic8uyGTDWxY=
github.com/spf13/cast v1.10.0/go.mod h1:jNfB8QC9IA6ZuY2ZjDp0KtFO2LZZlg4S/7bzP6qqeHo=
github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
github.com/spiffe/go-spiffe/v2 v2.8.1/go.mod h1:47Q0Q9/AqGha8QLHp+kxpH4Wca7X7EnOtlIJy3mxZ3U=
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
@@ -189,6 +224,7 @@ go.opentelemetry.io/otel/sdk/metric v1.46.0 h1:0piZ26EG4RBfebb2jhDH6ERCYHoVWduc3
go.opentelemetry.io/otel/sdk/metric v1.46.0/go.mod h1:I1PbKrdVc8Qu8HYVDNtqVIwLwjNrhsV/uFuxfwg8mO4=
go.opentelemetry.io/otel/trace v1.46.0 h1:OULy7ccdJnZtJ0UDYFOIGaCmiWzJ8Vi2G/Rsu60qs1c=
go.opentelemetry.io/otel/trace v1.46.0/go.mod h1:J7GAXweO77XSFkB/rmAqk9D6ihszhFjLU+d9WuUxDLI=
go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw=
go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg=
golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
@@ -198,9 +234,13 @@ golang.org/x/crypto v0.57.0 h1:3ZVCjf8Ggz7zneR/EHRVx68Ctf+2pmIMP2UFhh9cC6M=
golang.org/x/crypto v0.57.0/go.mod h1:Fdz0i5U6CoizGwLda9DttjSk6qlZo25zYNtR+ycvuZA=
golang.org/x/exp v0.0.0-20260908205506-85c1c2202aba h1:Ck8QetSgk912qxWLMCKxd0in+aiyBQyDSMae6e/xmpU=
golang.org/x/exp v0.0.0-20260908205506-85c1c2202aba/go.mod h1:50RgIsmK7OwqzTTeqcSXQW8SswW0o8fRcDxmqGluJ8E=
golang.org/x/image v0.0.0-20191009234506-e7c1f5e7dbb8/go.mod h1:FeLwcggjj3mMvU+oOTbSwawSJRM1uh48EjtB4UJZlP0=
golang.org/x/image v0.46.0 h1:b1+oYj0Jbp6K5MDT4i4/eZpYlk3V8SJhhDKh6LBHAyQ=
golang.org/x/image v0.46.0/go.mod h1:3B3W05VGVQyuXucLINLjXKrqISASfi4Xj+iCVkLMwew=
golang.org/x/mod v0.41.0 h1:qJmnOUb4YB+FsEuM3HcWucdZASCPGhsX6uljO6pog0c=
golang.org/x/mod v0.41.0/go.mod h1:Ek9pY8RKWXwsWvd3rQiHYtMqkjSUV+s1Rj7j4H5Ur6o=
golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
golang.org/x/net v0.0.0-20190603091049-60506f45cf65/go.mod h1:HSz+uSET+XFnRR8LxR5pz3Of3rY3CfYBVs4xY44aLks=
golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
golang.org/x/net v0.59.0 h1:5zfYln+w5XCxwrnMMJPufRgNoXEaGxl0wo5GqPXyues=
golang.org/x/net v0.59.0/go.mod h1:2DA/G1UfVbCpQPeWTmMPGY7Cs2PkBkwu743bVX5PIVg=
@@ -221,6 +261,7 @@ golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9sn
golang.org/x/term v0.46.0 h1:3+OXuTbaKDgwk8jTi3aSLHRlmWqHEUDUtxnbFigO4YE=
golang.org/x/term v0.46.0/go.mod h1:+K02xbkittuwc0Am4abfA3Fc+XRGXkvBXNO88NCXPoc=
golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
golang.org/x/text v0.3.2/go.mod h1:bEr9sfX3Q8Zfm5fL9x+3itogRgK3+ptLWKqgva+5dAk=
golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
golang.org/x/text v0.42.0 h1:JbOZXgfeCPU9gacVtYliJqOhD+zhrEqK4LfdpmlUZqI=
golang.org/x/text v0.42.0/go.mod h1:ojzP1Z+2QtioaF8DTtO8K5q7JWVVYwZKenzujK0Zd0E=
@@ -234,6 +275,7 @@ golang.org/x/tools/go/packages/packagestest v0.1.1-deprecated/go.mod h1:RVAQXBGN
gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
google.golang.org/api v0.293.0/go.mod h1:6n5tjEB1gzwniZTepZ0g5u+wM7Bof5GeULCx/zh8ZE0=
google.golang.org/appengine v1.6.5/go.mod h1:8WjMMxjGQR8xUklV/ARdw2HLXBOI7O7uCIDZVag1xfc=
google.golang.org/genproto/googleapis/api v0.0.0-20260918162117-cecb64721679 h1:FEp7JNE32DTAwbnI/ixagnmj7Xm1eTONofGEUXFjZ4w=
google.golang.org/genproto/googleapis/api v0.0.0-20260918162117-cecb64721679/go.mod h1:52bV8FLAQ9Qmcqaq9ECLmuEHZthk+6OPV45aKBBrsNw=
google.golang.org/genproto/googleapis/api v0.0.0-20260921155816-b14227669459 h1:GS9OIt/j7c8bvBjYNgnKQysVfmV7e4jM0H8ZK95G4t8=
@@ -256,8 +298,10 @@ gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
gotest.tools/v3 v3.5.2 h1:7koQfIKdy+I8UTetycgUqXWSDwpgv193Ka+qRsmBY8Q=
gotest.tools/v3 v3.5.2/go.mod h1:LtdLGcnqToBH83WByAAi/wiwSFCArdFIUV/xxN4pcjA=
modernc.org/cc/v4 v4.29.1 h1:MKgdCV3WykTSPqpVrnxdEDS0HEd2FHpKZDzxzU5LyeI=
modernc.org/cc/v4 v4.29.7 h1:q+NXGJ0bK3b4TXFYQQVr9pYETGnmwFWkrUzJnMya/Tg=
modernc.org/cc/v4 v4.29.7/go.mod h1:OnovgIhbbMXMu1aISnJ0wvVD1KnW+cAUJkIrAWh+kVI=
modernc.org/ccgo/v4 v4.34.6 h1:sBgfIwyN0TQ9C5hwIeuqyeAKyMWnbvj2fvpF4L11uzU=
modernc.org/ccgo/v4 v4.36.0 h1:T5h7ZMcrw2r94oDLtBcU3YI6e1W8DiUg2SJIs2fwD2s=
modernc.org/ccgo/v4 v4.36.0/go.mod h1:rrtGc2QkS239nYb/mQNuBMyjq3/y3ZXWbBjPoV3wqzA=
modernc.org/ccgo/v4 v4.36.1 h1:ZNIUZAryN0UgnJwtyxrdEzcFc3yD4Cu4AzjfPXsLsIE=
@@ -265,10 +309,13 @@ modernc.org/fileutil v1.4.0 h1:j6ZzNTftVS054gi281TyLjHPp6CPHr2KCxEXjEbD6SM=
modernc.org/fileutil v1.4.0/go.mod h1:EqdKFDxiByqxLk8ozOxObDSfcVOv/54xDs/DUHdvCUU=
modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI=
modernc.org/gc/v2 v2.6.5/go.mod h1:YgIahr1ypgfe7chRuJi2gD7DBQiKSLMPgBQe9oIiito=
modernc.org/gc/v3 v3.1.4 h1:2g65LGVSmFQrXeITAw97x7hCRvZFcyE1uDP+7Vng7JI=
modernc.org/gc/v3 v3.1.5 h1:21ldfPfRYE31Tb7B3mwAK8gy1AxP4+dKjrOQPfqakoc=
modernc.org/gc/v3 v3.1.5/go.mod h1:HFK/6AGESC7Ex+EZJhJ2Gni6cTaYpSMmU/cT9RmlfYY=
modernc.org/goabi0 v0.2.0 h1:HvEowk7LxcPd0eq6mVOAEMai46V+i7Jrj13t4AzuNks=
modernc.org/goabi0 v0.2.0/go.mod h1:CEFRnnJhKvWT1c1JTI3Avm+tgOWbkOu5oPA8eH8LnMI=
modernc.org/libc v1.74.4 h1:fX1Omw4o2/1C2iRkkIsrQTasJQldLhRmuPreXLoWs9k=
modernc.org/libc v1.74.4/go.mod h1:eeQAS9W3sZeKYMFubydxJpII9ybHWshk+7or7bLG9co=
modernc.org/libc v1.77.0 h1:wV+faa9ixRoUNlakU0fHLi/1kV2YLG8D8Ksk3c2mPtY=
modernc.org/libc v1.77.0/go.mod h1:BmXDCJcMkRMRbX2EI8+Zhh4fKWlHNbCCZEy0tiZevP4=
modernc.org/libc v1.77.1 h1:Ct8j47QtiZ1Enj2DtFXQtUqrPCAjdCmPjtCuvrYQ0Hs=
@@ -281,6 +328,8 @@ modernc.org/opt v0.2.0 h1:tGyef5ApycA7FSEOMraay9SaTk5zmbx7Tu+cJs4QKZg=
modernc.org/opt v0.2.0/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns=
modernc.org/sortutil v1.2.1 h1:+xyoGf15mM3NMlPDnFqrteY07klSFxLElE2PVuWIJ7w=
modernc.org/sortutil v1.2.1/go.mod h1:7ZI3a3REbai7gzCLcotuw9AC4VZVpYMjDzETGsSMqJE=
modernc.org/sqlite v1.57.0 h1:qNQP6xnx5M0ISNtlnxoOX0+cD5bJ0/gr9aMmndFczzg=
modernc.org/sqlite v1.57.0/go.mod h1:yCJ2cmAaIkHQ25oXWrF8H4O1lIfPYPR26yCEDj2P3pQ=
modernc.org/sqlite v1.59.0 h1:X1es1GpqBlS/5T+vbM4HLUdaa8OtQx468DF2vrx+38A=
modernc.org/sqlite v1.59.0/go.mod h1:+paeT2A3iPRHkQDwG7oA6Tk0zQd5woMEI8q7orfry8k=
modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0=
+10 -2
View File
@@ -169,8 +169,16 @@ echo "==> Building native archie binaries..."
# refuses to self-update (internal/releaseupdate.ErrUnknownInstallType)
# rather than guess whether /update's configured install command is
# even the right kind of update for a script-built native binary.
GATEWAY_VERSION="$(git describe --tags --match 'archied/v*' 2>/dev/null | sed 's|^archied/v||' || echo dev)"
RUNTIME_VERSION="$(git describe --tags --match 'archie/v*' 2>/dev/null | sed 's|^archie/v||' || echo dev)"
# A from-source build is not a release, and CI is the only thing that stamps
# one: the version a release carries is written into the artifact CI
# publishes -- the zip's binaries and the container image -- and is never
# derived from whatever tags a local checkout happens to have. Deriving it
# here made a source-built host claim a release it was not running, and made
# the stamp a function of the commit graph, which is the one input a
# content-checksum build cache cannot see (archie-core-pdq2). A source build
# says `dev`; its traceability is the checkout it came from.
GATEWAY_VERSION="dev"
RUNTIME_VERSION="dev"
LDFLAGS="-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion=${GATEWAY_VERSION}"
LDFLAGS="${LDFLAGS} -X github.com/samcharles93/archie-core/internal/app/archied.runtimeVersion=${RUNTIME_VERSION}"
LDFLAGS="${LDFLAGS} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary"
@@ -30,6 +30,7 @@ import (
"github.com/samcharles93/archie-core/internal/forge"
"github.com/samcharles93/archie-core/internal/forgerpc"
agentnats "github.com/samcharles93/archie-core/internal/infrastructure/agenttransport/nats"
"github.com/samcharles93/archie-core/internal/infrastructure/edastore"
"github.com/samcharles93/archie-core/internal/infrastructure/staterpc"
"github.com/samcharles93/archie-core/internal/infrastructure/workflowsteps"
"github.com/samcharles93/archie-core/internal/installtype"
@@ -376,9 +377,10 @@ func startStateStoreGRPC(t *testing.T, local *store.Store) string {
t.Fatal(err)
}
server := grpc.NewServer()
eda := edastore.OpenTest(t)
staterpc.RegisterServer(server, staterpc.Deps{
Tasks: local, Captures: local, Mappings: local, Bindings: local,
BindingDispatcher: local, BindingTaskCreator: local,
Tasks: local, Captures: eda, Mappings: eda, Bindings: eda,
BindingDispatcher: eda, BindingTaskCreator: local,
})
go func() { _ = server.Serve(listener) }()
t.Cleanup(func() { server.Stop(); _ = listener.Close() })
+4 -4
View File
@@ -5,15 +5,15 @@ import (
"strings"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/infrastructure/edastore"
"github.com/samcharles93/archie-core/internal/secret"
"github.com/samcharles93/archie-core/internal/store"
)
// bindingCipherFromConfig resolves the binding at-rest encryption key from
// config through the secret registry and returns a store cipher. An unset
// config through the secret registry and returns the EDA store's cipher. An unset
// encryption_key returns a nil cipher, keeping the legacy plaintext path (the
// store's default). See docs/prds/binding-secret-encryption.md.
func bindingCipherFromConfig(cfg config.Config, secrets *secret.Registry) (store.BindingCipher, error) {
func bindingCipherFromConfig(cfg config.Config, secrets *secret.Registry) (edastore.BindingCipher, error) {
if cfg.Bindings.EncryptionKey == (secret.SecretRef{}) {
return nil, nil
}
@@ -36,5 +36,5 @@ func bindingCipherFromConfig(cfg config.Config, secrets *secret.Registry) (store
previous = append(previous, v)
}
}
return store.NewBindingCipher(active, previous)
return edastore.NewBindingCipher(active, previous)
}
+21 -37
View File
@@ -45,8 +45,8 @@ import (
"github.com/samcharles93/archie-core/internal/forge"
forgewebhook "github.com/samcharles93/archie-core/internal/forge/webhook"
"github.com/samcharles93/archie-core/internal/gateway"
"github.com/samcharles93/archie-core/internal/indexing"
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
"github.com/samcharles93/archie-core/internal/infrastructure/edastore"
infraembedding "github.com/samcharles93/archie-core/internal/infrastructure/embedding"
"github.com/samcharles93/archie-core/internal/infrastructure/eventbus/nats"
infraMemory "github.com/samcharles93/archie-core/internal/infrastructure/memory"
@@ -65,7 +65,6 @@ import (
"github.com/samcharles93/archie-core/internal/skill"
"github.com/samcharles93/archie-core/internal/storage"
"github.com/samcharles93/archie-core/internal/tools"
toolsbuiltin "github.com/samcharles93/archie-core/internal/tools/builtin"
"github.com/samcharles93/archie-core/internal/tools/minimax"
toolprovider "github.com/samcharles93/archie-core/internal/tools/provider"
builtintoolprovider "github.com/samcharles93/archie-core/internal/tools/provider/builtin"
@@ -107,7 +106,8 @@ type boot struct {
playbooks *playbook.Store
st storecontract.TaskStore
st storecontract.TaskStore
eda *edastore.Store
// stateStore is the State Store contract adapter every daemon and gateway
// store consumer depends on. It is ALWAYS the remote *staterpc.Client
// dialed to the standalone archie-state-store gRPC service at
@@ -185,6 +185,9 @@ type boot struct {
lastReload func() config.ReloadStatus
natsClient *nats.Client
// reactionClient pulls the ARCHIE_REACTIONS fan-out stream; the daemon
// drains it each cycle to turn review reactions into remediate runs.
reactionClient *nats.Client
// natsURL is the endpoint the daemon's own client connected with at
// startup. For external mode it is cfg.NATS.URL; for embedded mode it is
// the embedded server's ClientURL(). Recorded so Daemon.ConnectedNATS
@@ -552,6 +555,7 @@ func (b *boot) connectNATS(ctx context.Context) error { //nolint:nestif // embed
// is the deliverable. A future producer (bead archie-core-8li9.3) will
// need its own publisher surface, wired when that step lands.
b.addCleanup(func() { reactionClient.Close() })
b.reactionClient = reactionClient
log.Info("nats connected", "url", url, "task_stream", nats.DefaultStreamName, "reaction_stream", nats.DefaultReactionStreamName)
return nil
}
@@ -1115,37 +1119,6 @@ func (b *boot) setupGuardrails() {
)
}
// workspaceIndex builds the optional codesearch index that narrows grep's
// candidate files. It returns a slice so a failure is simply "no index"
// rather than a typed-nil reaching the provider.
//
// Every failure degrades instead of propagating: grep falls back to its
// direct walk, which is what it did before this was wired at all. An
// accelerator that can refuse to build must never stop the daemon starting.
//
// The context is detached from cancellation but keeps its values, because
// NewManager starts an asynchronous build whose lifetime is the process
// while the gateway path's boot context is cancelled once startup returns.
// Inheriting cancellation would kill the build mid-flight and leave grep
// permanently unindexed with nothing to show why; using Background instead
// would silently drop any values the caller's context carries.
func (b *boot) workspaceIndex(ctx context.Context, workspace string) []toolsbuiltin.GrepIndex {
cfg, log := b.cfg, b.log
idxCfg := cfg.Indexing.WithDefaults(cfg.WorkDir)
manager, err := indexing.NewManager(
context.WithoutCancel(ctx),
indexing.Config{IndexDir: idxCfg.IndexDir, DBPath: idxCfg.DBPath, Log: log},
workspace,
)
if err != nil {
log.Warn("workspace index unavailable; grep will search unindexed",
"workspace", workspace, "index_dir", idxCfg.IndexDir, "error", err)
return nil
}
log.Info("workspace index enabled", "workspace", workspace, "index_dir", idxCfg.IndexDir)
return []toolsbuiltin.GrepIndex{manager}
}
// registerTools registers the tool providers with a lifecycle: workspace
// file/shell tools and optional MCP servers. Memory tools
// (memory_create/update/delete/list) are not registered here -- they are
@@ -1159,8 +1132,7 @@ func (b *boot) registerTools(ctx context.Context) error {
// deliberate choice rather than a default.
if workspace := cfg.Chat.Workspace; workspace != "" {
unrestricted := cfg.Chat.UnrestrictedFilesystem
index := b.workspaceIndex(ctx, workspace)
if err := b.providerRegistry.Register(builtintoolprovider.New(workspace, unrestricted, index...)); err != nil {
if err := b.providerRegistry.Register(builtintoolprovider.New(workspace, unrestricted)); err != nil {
log.Error("workspace tool provider registration failed", "err", err)
return err
}
@@ -1321,6 +1293,7 @@ func (b *boot) buildDaemon() {
Storage: b.storeBackend,
Log: log,
Tasks: b.natsClient,
Reactions: b.reactionClient,
WorktreeGrants: b.worktreeGrants,
StateStoreGrants: b.stateStoreGrants,
ContainerPool: b.containerPool,
@@ -1394,7 +1367,18 @@ func (b *boot) setupForgeWebhook() {
"engine", cfg.Forge.WebhookSecret.Engine, "key", cfg.Forge.WebhookSecret.Key, "err", err)
return
}
receiver := forgewebhook.New(secretValue, cfg.Dispatch.Trigger, cfg.Label, cfg.BotUser, b.d.PublishTask, log)
// The reaction publisher is the consumer's supply side: the same typed
// reaction the poll produces, keyed source-independently, so webhook and
// poll deliveries of one review dedup (pr-review-remediation.md
// decision 2).
publishReaction := func(ctx context.Context, reaction workintake.ReviewCommentEnvelope) error {
payload, err := reaction.Encode()
if err != nil {
return err
}
return b.d.Tasks.PublishUnique(ctx, reaction.Subject(), reaction.IdempotencyKey(), payload)
}
receiver := forgewebhook.New(secretValue, cfg.Dispatch.Trigger, cfg.Label, cfg.BotUser, b.d.PublishTask, publishReaction, log)
host, port := parseListenAddr(cfg.Forge.WebhookAddr, "0.0.0.0", 8645)
addr := fmt.Sprintf("%s:%d", host, port)
srv := &http.Server{Addr: addr, Handler: receiver}
-121
View File
@@ -1,121 +0,0 @@
package archied
import (
"context"
"encoding/json"
"flag"
"fmt"
"io"
"os"
"github.com/samcharles93/archie-core/internal/indexing"
)
// flagErrorOutput receives helper diagnostics. It is a variable so tests can
// capture them, and it is deliberately not stdout: the parent parses stdout
// as JSON, so a stray usage message there would corrupt the result.
var flagErrorOutput io.Writer = os.Stderr
// codesearchHelperCommand is the argv[1] token that switches archied out of
// daemon mode and into the codesearch helper.
//
// indexing.Manager deliberately runs the google/codesearch library in a child
// process: upstream calls fatal exits on a corrupt index and leaks mmapped
// regions, neither of which may be allowed to take down a long-lived daemon.
// The child it spawns is this binary, so this name is a contract with
// internal/indexing -- renaming either side silently disables indexed search
// and falls the agent back to unindexed grep.
const codesearchHelperCommand = "workspace-codesearch"
// IsCodesearchHelperArgs reports whether args (os.Args[1:]) selects the
// helper rather than the daemon.
func IsCodesearchHelperArgs(args []string) bool {
return len(args) > 0 && args[0] == codesearchHelperCommand
}
// RunCodesearchHelper executes one helper subcommand and returns a process
// exit code. Output is the machine-readable result the parent decodes; all
// diagnostics go to stderr so they cannot corrupt it.
func RunCodesearchHelper(args []string, out io.Writer) int {
if len(args) == 0 {
helperErrorf("%s: expected a subcommand (build|candidates)\n", codesearchHelperCommand)
return 2
}
ctx := context.Background()
switch args[0] {
case "build":
fs := newHelperFlagSet("build")
root := fs.String("root", "", "workspace root to index")
index := fs.String("index", "", "path of the index sidecar to write")
if err := fs.Parse(args[1:]); err != nil {
return 2
}
if *root == "" || *index == "" {
helperErrorf("build: --root and --index are required\n")
return 2
}
if err := indexing.BuildIndex(ctx, *root, *index); err != nil {
helperErrorf("build: %v\n", err)
return 1
}
return 0
case "candidates":
return runCandidates(args[1:], out)
default:
helperErrorf("%s: unknown subcommand %q\n", codesearchHelperCommand, args[0])
return 2
}
}
func newHelperFlagSet(name string) *flag.FlagSet {
fs := flag.NewFlagSet(name, flag.ContinueOnError)
fs.SetOutput(flagErrorOutput)
return fs
}
// runCandidates handles the "candidates" subcommand, returning candidate
// file paths as a JSON array on stdout.
func runCandidates(args []string, out io.Writer) int {
fs := newHelperFlagSet("candidates")
index := fs.String("index", "", "path of the index sidecar to query")
pattern := fs.String("pattern", "", "search pattern")
literal := fs.Bool("literal", false, "treat the pattern as a literal string")
caseSensitive := fs.Bool("case-sensitive", false, "match case sensitively")
if err := fs.Parse(args); err != nil {
return 2
}
if *index == "" || *pattern == "" {
helperErrorf("candidates: --index and --pattern are required\n")
return 2
}
files, err := indexing.IndexCandidates(*index, *pattern, *literal, *caseSensitive)
if err != nil {
helperErrorf("candidates: %v\n", err)
return 1
}
// The parent decodes a JSON array and treats any decode failure as
// "no index", so a nil slice must still marshal as [] rather than null.
if files == nil {
files = []string{}
}
encoded, err := json.Marshal(files)
if err != nil {
helperErrorf("candidates: encode result: %v\n", err)
return 1
}
if _, err := out.Write(encoded); err != nil {
helperErrorf("candidates: write result: %v\n", err)
return 1
}
return 0
}
// helperErrorf writes a diagnostic to stderr. The write result is ignored
// deliberately: if stderr is gone there is nowhere left to report it, and the
// exit code already carries the outcome the parent acts on.
func helperErrorf(format string, args ...any) {
_, _ = fmt.Fprintf(flagErrorOutput, format, args...)
}
-85
View File
@@ -1,85 +0,0 @@
package archied
import (
"encoding/json"
"os"
"path/filepath"
"slices"
"strings"
"testing"
)
func TestRunCodesearchHelper(t *testing.T) {
root := t.TempDir()
if err := os.WriteFile(filepath.Join(root, "a.txt"), []byte("alpha needle omega\n"), 0o600); err != nil {
t.Fatalf("write fixture: %v", err)
}
if err := os.WriteFile(filepath.Join(root, "b.txt"), []byte("nothing here\n"), 0o600); err != nil {
t.Fatalf("write fixture: %v", err)
}
indexPath := filepath.Join(t.TempDir(), "workspace.csearch")
t.Run("build writes an index sidecar", func(t *testing.T) {
var out strings.Builder
code := RunCodesearchHelper([]string{"build", "--root", root, "--index", indexPath}, &out)
if code != 0 {
t.Fatalf("build exit code = %d, want 0", code)
}
if _, err := os.Stat(indexPath); err != nil {
t.Fatalf("index sidecar not written: %v", err)
}
})
t.Run("candidates emits the JSON contract the manager decodes", func(t *testing.T) {
var out strings.Builder
code := RunCodesearchHelper([]string{
"candidates", "--index", indexPath, "--pattern", "needle",
}, &out)
if code != 0 {
t.Fatalf("candidates exit code = %d, want 0", code)
}
var files []string
if err := json.Unmarshal([]byte(out.String()), &files); err != nil {
t.Fatalf("decode candidates output %q: %v", out.String(), err)
}
if !slices.ContainsFunc(files, func(p string) bool {
return strings.HasSuffix(p, "a.txt")
}) {
t.Errorf("candidates = %v, want the file containing the needle", files)
}
})
invalid := []struct {
name string
args []string
}{
{name: "no subcommand", args: nil},
{name: "unknown subcommand", args: []string{"frobnicate"}},
{name: "build without root", args: []string{"build", "--index", indexPath}},
{name: "build without index", args: []string{"build", "--root", root}},
{name: "candidates without index", args: []string{"candidates", "--pattern", "x"}},
{name: "candidates without pattern", args: []string{"candidates", "--index", indexPath}},
}
for _, tc := range invalid {
t.Run(tc.name+" is rejected", func(t *testing.T) {
var out strings.Builder
if code := RunCodesearchHelper(tc.args, &out); code == 0 {
t.Errorf("exit code = 0, want non-zero for %v", tc.args)
}
})
}
}
// The manager shells out to argv[0] with this exact subcommand name, so a
// rename on either side silently disables indexed search.
func TestCodesearchHelperSubcommandIsRecognised(t *testing.T) {
if !IsCodesearchHelperArgs([]string{codesearchHelperCommand, "build"}) {
t.Errorf("IsCodesearchHelperArgs() did not recognise %q", codesearchHelperCommand)
}
if IsCodesearchHelperArgs([]string{"-once"}) {
t.Error("IsCodesearchHelperArgs() claimed a normal daemon flag")
}
if IsCodesearchHelperArgs(nil) {
t.Error("IsCodesearchHelperArgs() claimed an empty argument list")
}
}
@@ -1,206 +0,0 @@
package archied
import (
"encoding/json"
"log/slog"
"os"
"path/filepath"
"testing"
"time"
"github.com/samcharles93/archie-core/internal/app/controlplane"
controlpb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1"
"github.com/samcharles93/archie-core/internal/infrastructure/cronstore"
"github.com/samcharles93/archie-core/internal/store"
)
// migrationServer builds the validating side exactly as RunStateStore composes
// it: a store over a throwaway file and openStateStoreControlPlane, the root
// helper that registers the shared step vocabulary.
func migrationServer(t *testing.T) (*controlplane.Server, *store.Store) {
t.Helper()
st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "archie.db-tasks.sqlite"))
if err != nil {
t.Fatalf("open store: %v", err)
}
t.Cleanup(func() { _ = st.Close() })
server, err := openStateStoreControlPlane(st)
if err != nil {
t.Fatalf("open control plane: %v", err)
}
return server, st
}
// seedSchedules mirrors RunStateStore's ImportConfig: the schedules resource
// starts as the empty seed at version 1, which is the state the legacy
// migration runs against.
func seedSchedules(t *testing.T, control *controlplane.Server) int64 {
t.Helper()
seed, err := json.Marshal([]cronstore.JobSpec{})
if err != nil {
t.Fatalf("encode empty schedules seed: %v", err)
}
response, err := control.Command(t.Context(), &controlpb.CommandRequest{
Kind: controlplane.SchedulesKind, Command: "replace", ValueJson: seed,
ExpectedVersion: 0, Actor: "system:migration", Source: "legacy-config", RequestId: "import:schedules",
})
if err != nil {
t.Fatalf("seed schedules: %v", err)
}
return response.GetResource().GetVersion()
}
// writeLegacyJobs writes a legacy cronstore file at the layout
// migrateLegacySchedules reads: <dir of dbPath>/cron/jobs.json, in the
// store's own on-disk envelope shape (schema v2).
func writeLegacyJobs(t *testing.T, dir string, jobs []cronstore.JobSpec) string {
t.Helper()
data, err := json.Marshal(struct {
SchemaVersion int `json:"schema_version"`
Jobs []cronstore.JobSpec `json:"jobs"`
}{SchemaVersion: 2, Jobs: jobs})
if err != nil {
t.Fatalf("encode fixture: %v", err)
}
return writeLegacyFile(t, dir, string(data))
}
func writeLegacyFile(t *testing.T, dir, content string) string {
t.Helper()
path := filepath.Join(dir, "cron", "jobs.json")
if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
t.Fatalf("create legacy cron directory: %v", err)
}
if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
t.Fatalf("write legacy jobs file: %v", err)
}
return path
}
// legacyJob is a schema-v1-shaped job the old daemon's cron engine wrote.
// An empty Kind means chat, the pre-field default (cronstore.KindChat).
func legacyJob(id, kind string, interval time.Duration) cronstore.JobSpec {
stamped := time.Date(2026, 9, 1, 9, 0, 0, 0, time.UTC)
return cronstore.JobSpec{
ID: id, Kind: kind, Detail: "legacy " + id,
Schedule: cronstore.Schedule{Kind: cronstore.ScheduleInterval, Interval: cronstore.Duration(interval)},
NextRun: stamped, Created: stamped, Updated: stamped,
}
}
// storedScheduleIDs decodes the schedules resource into the job IDs it holds.
func storedScheduleIDs(t *testing.T, st *store.Store) []string {
t.Helper()
resource, err := st.Resource(t.Context(), controlplane.SchedulesKind)
if err != nil {
t.Fatalf("read schedules resource: %v", err)
}
var jobs []cronstore.JobSpec
if err := json.Unmarshal(resource.Value, &jobs); err != nil {
t.Fatalf("decode schedules resource: %v", err)
}
ids := make([]string, 0, len(jobs))
for _, job := range jobs {
ids = append(ids, job.ID)
}
return ids
}
// TestMigrateLegacySchedulesMovesOnlyWorkflowJobs: a legacy file holding a
// chat job (the pre-field default, kind omitted) and a workflow job migrates
// the workflow job and skips -- never refuses -- the chat one. The current
// behaviour replaces the whole list and lets the schedules validator fail the
// State Store on the chat job, taking every process that dials it down with
// it (archie-core-q6vw).
func TestMigrateLegacySchedulesMovesOnlyWorkflowJobs(t *testing.T) {
dir := t.TempDir()
dbPath := filepath.Join(dir, "archie.db-tasks.sqlite")
writeLegacyJobs(t, dir, []cronstore.JobSpec{
legacyJob("chat-daily", "", 24*time.Hour),
legacyJob("tdd-hourly", cronstore.KindWorkflow, time.Hour),
})
server, st := migrationServer(t)
version := seedSchedules(t, server)
migrateLegacySchedules(t.Context(), server, dbPath, version, discardLog())
got := storedScheduleIDs(t, st)
if len(got) != 1 || got[0] != "tdd-hourly" {
t.Fatalf("schedules resource holds %v, want only the migratable workflow job", got)
}
if _, err := os.Stat(path_migrated(dir)); err != nil {
t.Fatalf("migrated legacy file not marked (jobs.json.migrated): %v", err)
}
if _, err := os.Stat(filepath.Join(dir, "cron", "jobs.json")); !os.IsNotExist(err) {
t.Fatalf("legacy file still at its original path after a successful migration")
}
}
// path_migrated is where a completed migration leaves the legacy file.
func path_migrated(dir string) string {
return filepath.Join(dir, "cron", "jobs.json.migrated")
}
// TestMigrateLegacySchedulesKeepsStoreRunningWhenNothingIsMigratable: a
// legacy file holding only chat jobs leaves the schedules resource untouched
// and reports -- never fails -- the skip. The store's whole job is to come up.
func TestMigrateLegacySchedulesKeepsStoreRunningWhenNothingIsMigratable(t *testing.T) {
dir := t.TempDir()
dbPath := filepath.Join(dir, "archie.db-tasks.sqlite")
path := writeLegacyJobs(t, dir, []cronstore.JobSpec{
legacyJob("chat-daily", "", 24*time.Hour),
legacyJob("chat-weekly", "chat", 7*24*time.Hour),
})
server, st := migrationServer(t)
version := seedSchedules(t, server)
migrateLegacySchedules(t.Context(), server, dbPath, version, discardLog())
if _, err := os.Stat(path); err != nil {
t.Fatalf("legacy file removed though nothing was migrated: %v", err)
}
if got := storedScheduleIDs(t, st); len(got) != 0 {
t.Fatalf("schedules resource holds %v, want the untouched empty seed", got)
}
}
// TestMigrateLegacySchedulesKeepsStoreRunningOnUnreadableLegacyStore: a
// corrupt legacy file is a diagnosis, not a boot blocker. The store must come
// up on the empty seed and the file must stay in place for the operator.
func TestMigrateLegacySchedulesKeepsStoreRunningOnUnreadableLegacyStore(t *testing.T) {
dir := t.TempDir()
dbPath := filepath.Join(dir, "archie.db-tasks.sqlite")
path := writeLegacyFile(t, dir, "{not json")
server, _ := migrationServer(t)
version := seedSchedules(t, server)
migrateLegacySchedules(t.Context(), server, dbPath, version, discardLog())
if _, err := os.Stat(path); err != nil {
t.Fatalf("legacy file removed though it was never read: %v", err)
}
}
// TestMigrateLegacySchedulesLeavesTheFileWhenTheReplaceIsRefused: even a
// workflow job the schedules validator refuses is skipped and retried on the
// next start, the way ImportConfig skips a refused seed -- never fatal.
func TestMigrateLegacySchedulesLeavesTheFileWhenTheReplaceIsRefused(t *testing.T) {
dir := t.TempDir()
dbPath := filepath.Join(dir, "archie.db-tasks.sqlite")
path := writeLegacyJobs(t, dir, []cronstore.JobSpec{
legacyJob("broken-interval", cronstore.KindWorkflow, 0), // interval schedule with no interval
})
server, st := migrationServer(t)
version := seedSchedules(t, server)
migrateLegacySchedules(t.Context(), server, dbPath, version, discardLog())
if _, err := os.Stat(path); err != nil {
t.Fatalf("legacy file removed though the replace never landed: %v", err)
}
if got := storedScheduleIDs(t, st); len(got) != 0 {
t.Fatalf("schedules resource holds %v, want the untouched empty seed", got)
}
}
// discardLog returns a logger that drops every record: these tests pin the
// migration's effects on the resource and the file, not its reporting.
func discardLog() *slog.Logger {
return slog.New(slog.DiscardHandler)
}
+93 -1
View File
@@ -8,6 +8,7 @@ import (
"strconv"
"strings"
"sync"
"time"
"github.com/samcharles93/archie-core/internal/agentexec"
"github.com/samcharles93/archie-core/internal/app/agentworker"
@@ -15,6 +16,7 @@ import (
"github.com/samcharles93/archie-core/internal/domain/workflow"
"github.com/samcharles93/archie-core/internal/forge"
"github.com/samcharles93/archie-core/internal/gateway"
"github.com/samcharles93/archie-core/internal/infrastructure/artifactsync"
"github.com/samcharles93/archie-core/internal/worktree"
)
@@ -29,6 +31,9 @@ type prReviewer struct {
models map[string]string
providers map[string]agentexec.Provider
maxSteps int
// artifacts publishes the completed review to the collaborative editor.
// nil = publishing is disabled (no [artifacts] base_url configured).
artifacts artifactsync.Sender
// currentMaxSteps lets the composition root apply live control-plane
// versions to reviews that have not started yet. Tests and direct
// constructions retain maxSteps as the fallback.
@@ -115,7 +120,9 @@ func (r *prReviewer) ReviewPR(ctx context.Context, identity *string, repo string
MaxSteps: maxSteps,
})
r.logReview(key, model, report)
return mapReviewResult(repo, number, model, report), nil
result := mapReviewResult(repo, number, model, report)
return r.attachArtifact(ctx, result, identity, owner, name, number, report), nil
}
// authorize enforces the identity-scoped repository allow-list. A nil
@@ -174,6 +181,62 @@ func (r *prReviewer) logReview(key, model string, report workflow.ReviewReport)
"findings", len(report.Findings), "blocking", blocking)
}
// attachArtifact publishes the report when the sender is configured and
// records the editor deep link on the result. Publishing never fails the
// review: a failure degrades to an empty URL.
func (r *prReviewer) attachArtifact(ctx context.Context, result gateway.PRReviewResult, identity *string, owner, name string, number int, report workflow.ReviewReport) gateway.PRReviewResult {
result.ArtifactURL = r.publishArtifact(ctx, reviewActor(identity), owner, name, number, report)
return result
}
// reviewActor resolves the attribution: the requesting chat identity when one
// exists, else the daemon's operator-reviewer actor.
func reviewActor(identity *string) string {
if identity != nil && *identity != "" {
return *identity
}
return "system:pr-reviewer"
}
// publishArtifact renders the report and hands it to the collaborative
// editor when artifact publishing is configured. It returns the editor deep
// link, or "" when publishing is disabled or failed: a publish failure is a
// logged degradation, never an error that fails the producing review.
func (r *prReviewer) publishArtifact(ctx context.Context, actor, owner, name string, number int, report workflow.ReviewReport) string {
if r.artifacts == nil {
return ""
}
title := fmt.Sprintf("Review of %s/%s#%d", owner, name, number)
artifact := artifactsync.Artifact{
Title: title,
Source: report.RenderMarkdown(title),
Meta: artifactsync.Meta{
Format: "markdown",
Category: "pr-review",
Visibility: "account-only",
Egress: "none",
Actor: actor,
Origin: "pr-review",
RequestID: "artifact:pr-review:" + owner + "/" + name + "#" + strconv.Itoa(number),
Version: "r1",
SentAt: time.Now().UTC(),
Task: &artifactsync.Task{Owner: owner, Repo: name, Number: number},
},
}
url, err := r.artifacts.Publish(ctx, artifact)
if err != nil {
if r.log != nil {
r.log.Warn("artifact publish failed; the review result is unaffected",
"artifact", artifact.RequestID(), "err", err)
}
return ""
}
if r.log != nil {
r.log.Info("artifact published", "artifact", artifact.RequestID(), "url", url)
}
return url
}
// splitOwnerRepo splits "owner/name" with the same validation the gateway's
// task_spawn allow-list uses.
func splitOwnerRepo(s string) (owner, repo string, err error) {
@@ -264,6 +327,7 @@ func (b *boot) prReviewer() gateway.ChatPRReviewer {
models: b.cfg.Models,
providers: executionProviders(b.cfg),
maxSteps: maxSteps,
artifacts: b.artifactSender(),
allowed: buildReviewAllowlist(b.cfg),
log: b.log,
}
@@ -273,3 +337,31 @@ func (b *boot) prReviewer() gateway.ChatPRReviewer {
b.chatPRReviewer = review
return b.chatPRReviewer
}
// artifactSender builds the collaborative-editor sender when the [artifacts]
// section configures one. An empty base_url disables publishing entirely; a
// base_url with an unresolvable token is a missing credential, which disables
// the capability with a loud warning rather than stopping the daemon
// (docs/architecture/configuration.md, "A missing credential disables a
// capability").
func (b *boot) artifactSender() artifactsync.Sender {
cfg := b.cfg.Artifacts
if cfg.BaseURL == "" {
return nil
}
token, err := b.secrets.Resolve(cfg.Token)
if err != nil {
b.log.Warn("artifact publishing disabled: the service credential could not be resolved",
"base_url", cfg.BaseURL, "token_engine", cfg.Token.Engine, "err", err)
return nil
}
if token == "" {
token = b.secrets.Getenv(cfg.TokenEnv)
}
if token == "" {
b.log.Warn("artifact publishing disabled: no service token; set the token secret or its environment variable",
"base_url", cfg.BaseURL, "token_env", cfg.TokenEnv)
return nil
}
return artifactsync.NewClient(cfg.BaseURL, token)
}
+74
View File
@@ -2,13 +2,16 @@ package archied
import (
"context"
"errors"
"log/slog"
"strings"
"testing"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/workflow"
"github.com/samcharles93/archie-core/internal/forge"
"github.com/samcharles93/archie-core/internal/gateway"
"github.com/samcharles93/archie-core/internal/infrastructure/artifactsync"
"github.com/samcharles93/archie-core/internal/tools"
"github.com/samcharles93/archie-core/internal/worktree"
)
@@ -241,3 +244,74 @@ func hasReviewPRTool(entries []tools.ToolEntry) bool {
}
return false
}
type fakeArtifactSender struct {
calls int
url string
err error
last artifactsync.Artifact
}
func (f *fakeArtifactSender) Publish(_ context.Context, a artifactsync.Artifact) (string, error) {
f.calls++
f.last = a
if f.err != nil {
return "", f.err
}
return f.url, nil
}
func TestPrReviewerPublishesTheCompletedReview(t *testing.T) {
fake := &fakeArtifactSender{url: "https://offloaded.dev/collab?document=a_1"}
r := &prReviewer{artifacts: fake, log: slog.New(slog.DiscardHandler)}
report := workflow.NewCompletedReviewReport([]workflow.ReviewFinding{{
File: "handler.go", Line: 42, Defect: "nil deref",
FailureScenario: "empty payload crashes", Verdict: workflow.ReviewVerdictConfirmed,
Level: workflow.ReviewLevelError,
}}, "one finding")
report.Checked = []workflow.ReviewCheck{{Property: "p", Evidence: "e"}}
url := r.publishArtifact(context.Background(), "system:pr-reviewer", "acme", "widget", 7, report)
if url != fake.url {
t.Fatalf("publishArtifact = %q, want the sender's url %q", url, fake.url)
}
if fake.calls != 1 {
t.Fatalf("Publish called %d times, want 1", fake.calls)
}
got := fake.last
if got.Meta.Format != "markdown" || got.Meta.Category != "pr-review" {
t.Fatalf("format/category = %s/%s, want markdown/pr-review", got.Meta.Format, got.Meta.Category)
}
if got.Meta.Actor != "system:pr-reviewer" || got.Meta.Origin != "pr-review" {
t.Fatalf("attribution = %s/%s", got.Meta.Actor, got.Meta.Origin)
}
if got.Meta.Visibility != "account-only" || got.Meta.Egress != "none" {
t.Fatalf("visibility/egress = %s/%s", got.Meta.Visibility, got.Meta.Egress)
}
if got.Title != "Review of acme/widget#7" {
t.Fatalf("title = %q", got.Title)
}
if got.Meta.RequestID != "artifact:pr-review:acme/widget#7" {
t.Fatalf("requestId = %q, want the deterministic artifact key", got.Meta.RequestID)
}
if got.Meta.Task == nil || got.Meta.Task.Owner != "acme" || got.Meta.Task.Number != 7 {
t.Fatalf("task coordinates = %+v", got.Meta.Task)
}
if !strings.Contains(got.Source, "## Findings") {
t.Fatalf("source is not the rendered report:\n%s", got.Source)
}
}
func TestPrReviewerPublishDegradesOnSenderFailure(t *testing.T) {
r := &prReviewer{artifacts: &fakeArtifactSender{err: errors.New("503 exhausted")}, log: slog.New(slog.DiscardHandler)}
if url := r.publishArtifact(context.Background(), "system:pr-reviewer", "acme", "widget", 7, workflow.NewCompletedReviewReport(nil, "s")); url != "" {
t.Fatalf("url = %q, want empty on a failed publish", url)
}
}
func TestPrReviewerPublishIsANoOpWithoutASender(t *testing.T) {
r := &prReviewer{}
if url := r.publishArtifact(context.Background(), "system:pr-reviewer", "acme", "widget", 7, workflow.NewCompletedReviewReport(nil, "s")); url != "" {
t.Fatalf("url = %q, want empty when the sender is disabled", url)
}
}
+16 -7
View File
@@ -14,7 +14,6 @@ import (
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
"github.com/samcharles93/archie-core/internal/infrastructure/crondelivery"
"github.com/samcharles93/archie-core/internal/infrastructure/cronevents"
"github.com/samcharles93/archie-core/internal/infrastructure/cronstore"
)
// schedulingConfig translates external input into the domain-owned engine
@@ -75,7 +74,7 @@ func (b *boot) setupScheduling() error {
if err != nil {
return fmt.Errorf("scheduling: build workflow runner: %w", err)
}
router, err := crondelivery.NewRouter(store, map[string]scheduling.Runner{cronstore.KindWorkflow: workflowRunner}, cfg.Events)
router, err := crondelivery.NewRouter(store, map[string]scheduling.Runner{scheduling.KindWorkflow: workflowRunner}, cfg.Events)
if err != nil {
return fmt.Errorf("scheduling: build router: %w", err)
}
@@ -93,17 +92,27 @@ type scheduleResourceStore struct {
client *controlplane.Client
}
func (s scheduleResourceStore) Get(ctx context.Context, id string) (cronstore.JobSpec, bool, error) {
// The schedules document behind the control plane is the production
// RouterStore: it resolves a job id to its spec and records a completed run.
// The assertions this replaces used to pin the retired file-backed store;
// crondelivery's contract comments name this type as the implementation.
var (
_ crondelivery.SpecLookup = scheduleResourceStore{}
_ crondelivery.RunRecorder = scheduleResourceStore{}
_ crondelivery.RouterStore = scheduleResourceStore{}
)
func (s scheduleResourceStore) Get(ctx context.Context, id string) (scheduling.JobSpec, bool, error) {
jobs, _, err := s.client.Schedules(ctx)
if err != nil {
return cronstore.JobSpec{}, false, err
return scheduling.JobSpec{}, false, err
}
for _, job := range jobs {
if job.ID == id {
return job, true, nil
}
}
return cronstore.JobSpec{}, false, nil
return scheduling.JobSpec{}, false, nil
}
func (s scheduleResourceStore) Due(ctx context.Context, now time.Time) ([]scheduling.Job, error) {
@@ -132,7 +141,7 @@ func (s scheduleResourceStore) MarkRun(ctx context.Context, id string, runAt tim
continue
}
found = true
if jobs[index].Schedule.Resolved().Kind == cronstore.ScheduleOnce {
if jobs[index].Schedule.Resolved().Kind == scheduling.ScheduleOnce {
jobs = append(jobs[:index], jobs[index+1:]...)
break
}
@@ -146,7 +155,7 @@ func (s scheduleResourceStore) MarkRun(ctx context.Context, id string, runAt tim
break
}
if !found {
return fmt.Errorf("%w: id %q", cronstore.ErrJobNotFound, id)
return fmt.Errorf("%w: id %q", scheduling.ErrJobNotFound, id)
}
_, err = s.client.ReplaceSchedules(ctx, jobs, version, "system:scheduler", "scheduler", fmt.Sprintf("schedule-run:%s:%d", id, runAt.UnixNano()))
if err == nil {
+97 -99
View File
@@ -13,10 +13,8 @@ import (
"context"
"encoding/json"
"fmt"
"log/slog"
"net"
"net/http"
"os"
"path/filepath"
"time"
@@ -24,12 +22,12 @@ import (
"github.com/samcharles93/archie-core/internal/app/controlplane"
"github.com/samcharles93/archie-core/internal/config"
controlpb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1"
"github.com/samcharles93/archie-core/internal/domain/health"
"github.com/samcharles93/archie-core/internal/domain/identity"
"github.com/samcharles93/archie-core/internal/domain/storecontract"
"github.com/samcharles93/archie-core/internal/infrastructure/cronstore"
"github.com/samcharles93/archie-core/internal/infrastructure/edastore"
"github.com/samcharles93/archie-core/internal/infrastructure/readiness"
"github.com/samcharles93/archie-core/internal/infrastructure/stateadmin"
"github.com/samcharles93/archie-core/internal/infrastructure/staterpc"
"github.com/samcharles93/archie-core/internal/store"
)
@@ -49,6 +47,11 @@ func configuredIdentityNames(cfg config.Config) []string {
return names
}
// edaDBPath derives the event-capture database from the configured db_path,
// beside the task database rather than inside it: the two stores have separate
// lifecycles and only meet at binding_dispatches.task_id.
func edaDBPath(configuredPath string) string { return configuredPath + "-eda.sqlite" }
// StateStoreOptions contains process inputs for the standalone State Store.
type StateStoreOptions struct {
Config string
@@ -65,6 +68,10 @@ type StateStoreOptions struct {
// address: GET /healthz (liveness) and GET /health/detailed (the
// state_db probe). Empty disables it.
ReadyAddr string
// AdminAddr, when non-empty, starts the read-only operator dashboard on
// the address. It co-tenants on the same SQLite file this process already
// owns, so it needs no lock and no database of its own. Empty disables it.
AdminAddr string
}
// RunStateStore owns the single archie.db SQLite file, registers every
@@ -107,12 +114,11 @@ func RunStateStore(ctx context.Context, options StateStoreOptions) error {
if err != nil {
return err
}
versions, skipped, err := control.ImportConfig(ctx, b.cfg)
_, skipped, err := control.ImportConfig(ctx, b.cfg)
if err != nil {
return fmt.Errorf("import control-plane resources: %w", err)
}
b.reportUnseededResources(skipped)
migrateLegacySchedules(ctx, control, b.cfg.DBPath, versions[controlplane.SchedulesKind], b.log)
token := options.Token
if token == "" {
@@ -131,10 +137,8 @@ func RunStateStore(ctx context.Context, options StateStoreOptions) error {
defer listener.Close()
b.log.Info("archie-state-store running", "addr", listener.Addr().String(), "token_required", !loopback)
if options.ReadyAddr != "" {
if err := b.startStateStoreReadiness(ctx, options.ReadyAddr); err != nil {
return err
}
if err := b.startOptionalSurfaces(ctx, options); err != nil {
return err
}
deps := b.stateStoreDeps(grants)
@@ -188,81 +192,6 @@ func openStateStoreControlPlane(resources controlplane.ResourceStore) (*controlp
return server, nil
}
// migrateLegacySchedules carries a legacy cronstore file -- the old daemon's
// <state dir>/cron/jobs.json -- into the schedules resource, once, on a fresh
// seed. It moves only the jobs the schedules resource can hold: workflow
// jobs, the one delivery the router maps. Chat and unrecognised kinds were
// already dead deliveries in the old engine (the delivery router maps
// KindWorkflow alone), so they are reported and left in the legacy file
// rather than being allowed to refuse the replace the whole store depends on.
//
// Nothing here is fatal. The migration is a legacy-data courtesy: an
// unreadable or refused sidecar is logged and left in place for the next
// start, the way ImportConfig skips a seed the resource validator refuses --
// a value this process cannot use must not stop the one process every other
// process dials (docs/prds/runtime-control-plane.md, "Bootstrap, migration,
// and recovery"). A successful replace is marked by renaming the file to
// jobs.json.migrated, so the whole legacy list -- the skipped jobs included
// -- stays on disk for the operator; until the rename lands, the replaying
// request ID keeps the replace idempotent across restarts.
func migrateLegacySchedules(ctx context.Context, control *controlplane.Server, dbPath string, version int64, log *slog.Logger) {
if version != 1 {
return
}
path := filepath.Join(filepath.Dir(dbPath), "cron", "jobs.json")
if _, err := os.Stat(path); err != nil {
if os.IsNotExist(err) {
return
}
log.Warn("legacy cron store not readable; schedules migration skipped and retried on the next start", "path", path, "err", err)
return
}
jobs, err := readLegacyJobs(ctx, path)
if err != nil {
log.Error("legacy cron store unreadable; schedules migration skipped and retried on the next start", "path", path, "err", err)
return
}
migratable := make([]cronstore.JobSpec, 0, len(jobs))
for _, job := range jobs {
if job.Kind == cronstore.KindWorkflow {
migratable = append(migratable, job)
continue
}
log.Warn("legacy cron job is not a workflow job; the schedules resource does not carry it and it stays in the legacy file", "id", job.ID, "kind", job.Kind)
}
if len(migratable) == 0 {
log.Info("legacy cron store holds no workflow jobs; nothing to migrate", "path", path, "jobs", len(jobs))
return
}
value, err := json.Marshal(migratable)
if err != nil {
log.Error("encode legacy cron jobs; schedules migration skipped and retried on the next start", "path", path, "err", err)
return
}
if _, err := control.Command(ctx, &controlpb.CommandRequest{Kind: controlplane.SchedulesKind, Command: "replace", ValueJson: value, ExpectedVersion: 1, Actor: "system:migration", Source: "legacy-cronstore", RequestId: "import:legacy-schedules"}); err != nil {
log.Error("legacy cron jobs do not satisfy the schedules resource; migration skipped and retried on the next start", "path", path, "err", err)
return
}
if err := os.Rename(path, path+".migrated"); err != nil {
log.Error("mark the migrated legacy cron file; migration retried on the next start", "path", path, "err", err)
}
}
// readLegacyJobs reads the legacy cronstore file and closes its handle,
// reporting whichever failure came first.
func readLegacyJobs(ctx context.Context, path string) ([]cronstore.JobSpec, error) {
legacy, err := cronstore.Open(path)
if err != nil {
return nil, err
}
jobs, listErr := legacy.List(ctx)
closeErr := legacy.Close()
if listErr != nil {
return nil, listErr
}
return jobs, closeErr
}
// openStateStore opens the single task-store SQLite file exactly once for
// service ownership. It resolves secrets (for the binding cipher) but does
// NOT open gateway chat sessions -- those live in the separate archie-gateway
@@ -298,7 +227,23 @@ func (b *boot) openStateStore(ctx context.Context) error {
log.Error("release state store ownership", "err", err)
}
})
st, err := openProductionTaskStore(ctx, path, store.WithBindingCipher(bindingCipher))
eda, err := edastore.Open(edastore.Config{
DBPath: edaDBPath(cfg.DBPath),
DataDir: filepath.Join(filepath.Dir(path), "eda"),
Cipher: bindingCipher,
})
if err != nil {
log.Error("open event-capture store", "err", err)
return err
}
b.eda = eda
b.addCleanup(func() {
if err := eda.Close(); err != nil {
log.Error("close event-capture store", "err", err)
}
})
st, err := openProductionTaskStore(ctx, path)
if err != nil {
log.Error("open state store", "err", err)
return err
@@ -345,20 +290,24 @@ func (b *boot) stateStoreDeps(grants *staterpc.TaskGrants) staterpc.Deps {
if b.taskLogs != nil {
deps.TaskLogs = b.taskLogs
}
if cs, ok := b.st.(storecontract.CaptureStore); ok {
deps.Captures = cs
// The event-capture contracts are served by the PocketBase store, not the
// task store: those tables moved. BindingTaskCreator stays below on the
// task store, because creating a task is the one thing it still does.
if b.eda != nil {
deps.Captures = b.eda
deps.Mappings = b.eda
deps.Bindings = b.eda
deps.BindingDispatcher = b.eda
deps.PlaybookDispatcher = b.eda
}
if ms, ok := b.st.(storecontract.MappingStore); ok {
deps.Mappings = ms
}
if bs, ok := b.st.(storecontract.BindingStore); ok {
deps.Bindings = bs
}
if bd, ok := b.st.(storecontract.BindingDispatcher); ok {
deps.BindingDispatcher = bd
}
if pd, ok := b.st.(storecontract.PlaybookDispatcher); ok {
deps.PlaybookDispatcher = pd
// tool_call events project into the tool_calls collection on the same
// event-capture store: this process legitimately owns both, so the
// projection rides on the task-store surface it decorates. With no
// event-capture store (or no task store) there is nothing to project
// through, and Tasks passes through unwrapped rather than decorating a
// nil operand.
if b.eda != nil && b.st != nil {
deps.Tasks = newToolCallProjectingTaskStore(b.st, b.eda, b.log)
}
if btc, ok := b.st.(storecontract.BindingTaskCreator); ok {
deps.BindingTaskCreator = btc
@@ -421,6 +370,55 @@ func (b *boot) startStateStoreReadiness(ctx context.Context, readyAddr string) e
return b.serveHealth(ctx, readyAddr, mux, "state store readiness")
}
// startOptionalSurfaces starts the HTTP surfaces this process serves beside
// the gRPC contract, each enabled only by its own flag.
//
// They are gathered here rather than branched inline because RunStateStore is
// at its complexity budget: a surface that is off by default belongs to its
// own decision, not to the boot sequence that triggers it -- the same reason
// reportUnseededResources is a method.
func (b *boot) startOptionalSurfaces(ctx context.Context, options StateStoreOptions) error {
if options.ReadyAddr != "" {
if err := b.startStateStoreReadiness(ctx, options.ReadyAddr); err != nil {
return err
}
}
if options.AdminAddr != "" {
if err := b.startStateAdmin(ctx, options.AdminAddr); err != nil {
return err
}
}
return nil
}
// startStateAdmin starts the read-only operator dashboard on adminAddr.
//
// It is started here, inside the process that already holds the database's
// ownership claim (openStateStore above), because that claim is what makes a
// second reader safe to co-tenant: a separate admin process would be a second
// opener of a single-owner file. The surface exposes view collections only and
// refuses the routes that could write, so the StateStoreService contract this
// process serves stays the only writer of task state.
func (b *boot) startStateAdmin(ctx context.Context, adminAddr string) error {
admin, err := stateadmin.New(stateadmin.Config{
DBPath: taskDBPath(b.cfg.DBPath),
DataDir: filepath.Join(filepath.Dir(taskDBPath(b.cfg.DBPath)), "admin"),
})
if err != nil {
return err
}
b.addCleanup(func() {
if err := admin.Close(); err != nil {
b.log.Error("close state admin", "err", err)
}
})
handler, err := admin.Handler()
if err != nil {
return fmt.Errorf("build state admin handler: %w", err)
}
return b.serveHealth(ctx, adminAddr, handler, "state store admin")
}
// stateStoreServerOpts applies the transport security boundary (§9): a
// loopback listener is served insecure with no token; any non-loopback
// address requires a bearer token, else the process fails closed. It cannot
@@ -6,6 +6,7 @@ import (
"testing"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/infrastructure/edastore"
taskactionstore "github.com/samcharles93/archie-core/internal/infrastructure/taskactions"
"github.com/samcharles93/archie-core/internal/store"
)
@@ -15,14 +16,33 @@ import (
// b.stateStore rather than b.st: the two differ by identity, so an assertion
// that a consumer field holds storeB (not storeA) can only pass if the wiring
// reads b.stateStore.
func openSecondStore(t *testing.T) *store.Store {
// stateStoreAdapter stands in for the real adapter (*staterpc.Client), which
// fronts both halves of the contract over one connection: the task store and
// the event-capture store. A plain *store.Store no longer satisfies the
// event-capture surfaces, so a test that asserts "everything routes through
// the adapter" needs something that implements them, exactly as the client
// does in production.
// edaSide aliases the event-capture store so it can be embedded beside
// *store.Store: both are named Store, and Go allows only one embedded field
// per name.
type edaSide = edastore.Store
type stateStoreAdapter struct {
*store.Store
*edaSide
}
// Close disambiguates the two embedded stores, which both have one.
func (a *stateStoreAdapter) Close() error { return a.Store.Close() }
func openSecondStore(t *testing.T) *stateStoreAdapter {
t.Helper()
st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "state-store.db"))
if err != nil {
t.Fatalf("open second store: %v", err)
}
t.Cleanup(func() { _ = st.Close() })
return st
return &stateStoreAdapter{Store: st, edaSide: edastore.OpenTest(t)}
}
// TestBuildDaemonRoutesTaskStoreThroughStateStore proves the daemon's task
@@ -2,14 +2,11 @@ package archied
import (
"context"
"errors"
"strings"
"testing"
"time"
"google.golang.org/grpc"
"google.golang.org/grpc/codes"
"google.golang.org/grpc/status"
"google.golang.org/grpc/test/bufconn"
controlpb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1"
@@ -137,23 +134,25 @@ func TestStateStoreServerOptionsTolerateTheDialersKeepalive(t *testing.T) {
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
t.Parallel()
elapsed, recvErr := holdWatch(t, tc.opts, keepaliveWindow)
elapsed, recvErr, survived := holdWatch(t, tc.opts, keepaliveWindow)
// The server never writes, so the stream can only end because the
// window ran out or because the connection was torn down under it.
expired := streamEndedByWindow(recvErr)
t.Logf("watch ended after %s with %v", elapsed, recvErr)
if tc.tornDown {
if recvErr == nil || expired {
// connection was torn down under it, or because it outlived the window.
// Which one happened is the select in holdWatch, not the error the
// window's closure surfaces: see holdWatch for why reading the error
// made this case flaky.
t.Logf("watch lasted %s, survived the window: %v, ended with %v", elapsed, survived, recvErr)
if survived {
if tc.tornDown {
t.Fatalf("the dialer's watch was still open after %s: the default EnforcementPolicy (MinTime 5m) must strike pings that arrive 10s apart and answer with GOAWAY too_many_pings, so this case is not reaching the strike budget and the case below would prove nothing", keepaliveWindow)
}
if !strings.Contains(recvErr.Error(), "too_many_pings") {
t.Fatalf("the dialer's watch ended after %s with %v: want GOAWAY too_many_pings, not some other connection loss", elapsed, recvErr)
}
return
}
if recvErr == nil || !expired {
if !tc.tornDown {
t.Fatalf("the dialer's watch ended after %s: %v\nA watch carrying no traffic must survive on the pings staterpc.Dial sends; a server policy that strikes them answers a quiet connection with a dead one at ~40s, which is worse than the keepalive it was added for", elapsed, recvErr)
}
if !strings.Contains(recvErr.Error(), "too_many_pings") {
t.Fatalf("the dialer's watch ended after %s with %v: want GOAWAY too_many_pings, not some other connection loss", elapsed, recvErr)
}
})
}
}
@@ -172,11 +171,30 @@ func (w *quietWatch) Watch(_ *controlpb.WatchRequest, stream controlpb.ControlPl
return stream.Context().Err()
}
// keepaliveSlack keeps the stream's own deadline clear of the observation window.
// They must not be the same duration. The question holdWatch answers is whether
// the link outlives the window, and with the two identical the client deadline
// resolves microseconds after the timer either way: Recv returns
// DeadlineExceeded and the answer becomes a race between two timers rather than
// a fact about the link. Measured -- the same 50s window reported the healthy
// case as "ended" at 49.998s while the timer was still pending.
const keepaliveSlack = 5 * time.Second
// holdWatch serves opts over bufconn, dials it with the shipped dialer
// (staterpc.Dial, so the client keepalive is exactly the one the daemon, the
// dashboard and the agent container run), holds one watch stream open for
// window, and reports how long the stream lasted and how it ended.
func holdWatch(t *testing.T, opts []grpc.ServerOption, window time.Duration) (time.Duration, error) {
// window, and reports how long the stream lasted, how it ended, and whether it
// outlived the window.
//
// That last report is the property under test, and it is decided by which arm of
// a select wins rather than by the flavour of the error the window's closure
// surfaces. Reading the error instead -- asking for DeadlineExceeded -- made the
// tolerant case flaky under load: the client deadline, the server's stream
// context and the transport all resolve within microseconds of one another, so a
// watch that was still perfectly open was reported as Canceled or Unavailable,
// and a healthy link failed a test about unhealthy links. Measured on a loaded
// 16-core host at 49.999s into a 50s window.
func holdWatch(t *testing.T, opts []grpc.ServerOption, window time.Duration) (time.Duration, error, bool) {
t.Helper()
listener := bufconn.Listen(1 << 20)
watch := &quietWatch{started: make(chan struct{})}
@@ -194,7 +212,7 @@ func holdWatch(t *testing.T, opts []grpc.ServerOption, window time.Duration) (ti
})
client := dialStateStore(t, listener, restartAdminToken)
ctx, cancel := context.WithTimeout(t.Context(), window)
ctx, cancel := context.WithTimeout(t.Context(), window+keepaliveSlack)
defer cancel()
stream, err := client.ControlPlane().Watch(ctx, &controlpb.WatchRequest{Kind: "any"})
if err != nil {
@@ -206,14 +224,17 @@ func holdWatch(t *testing.T, opts []grpc.ServerOption, window time.Duration) (ti
t.Fatal("the server never started the watch stream")
}
start := time.Now()
// The server never writes, so this returns only when the window ends or the
// connection dies.
_, recvErr := stream.Recv()
return time.Since(start), recvErr
}
// streamEndedByWindow reports whether err is the window running out rather than
// the connection being torn down under it.
func streamEndedByWindow(err error) bool {
return err != nil && (errors.Is(err, context.DeadlineExceeded) || status.Code(err) == codes.DeadlineExceeded)
// Buffered so the receiving goroutine cannot outlive the call: cancel runs on
// the way out, Recv returns, and the send still has somewhere to land.
recv := make(chan error, 1)
go func() {
_, err := stream.Recv()
recv <- err
}()
select {
case err := <-recv:
return time.Since(start), err, false
case <-time.After(window):
return time.Since(start), nil, true
}
}
+7 -2
View File
@@ -12,6 +12,7 @@ import (
"github.com/samcharles93/archie-core/internal/config"
pb "github.com/samcharles93/archie-core/internal/contracts/state/v1"
"github.com/samcharles93/archie-core/internal/domain/storecontract"
"github.com/samcharles93/archie-core/internal/infrastructure/edastore"
"github.com/samcharles93/archie-core/internal/infrastructure/staterpc"
"github.com/samcharles93/archie-core/internal/logging"
"github.com/samcharles93/archie-core/internal/store"
@@ -145,12 +146,16 @@ func TestStateStoreDepsServePlaybookDispatcher(t *testing.T) {
b := newBootstrap()
b.st = st
// The playbook ledger moved to the event-capture store with the rest of
// the dispatch tables; the task store no longer serves it.
eda := edastore.OpenTest(t)
b.eda = eda
deps := b.stateStoreDeps(&staterpc.TaskGrants{})
if deps.PlaybookDispatcher == nil {
t.Fatal("stateStoreDeps leaves PlaybookDispatcher nil; the standalone State Store is the only production server for the playbook dispatch ledger")
}
if deps.PlaybookDispatcher != storecontract.PlaybookDispatcher(st) {
t.Fatalf("PlaybookDispatcher = %T, want the opened *store.Store", deps.PlaybookDispatcher)
if deps.PlaybookDispatcher != storecontract.PlaybookDispatcher(eda) {
t.Fatalf("PlaybookDispatcher = %T, want the opened *edastore.Store", deps.PlaybookDispatcher)
}
// A boot without a store must not fabricate one: nil keeps the RPCs honest
// as unavailable rather than depending on a nil receiver.
@@ -0,0 +1,87 @@
package archied
import (
"context"
"log/slog"
"sync/atomic"
"github.com/samcharles93/archie-core/internal/domain/storecontract"
"github.com/samcharles93/archie-core/internal/events"
"github.com/samcharles93/archie-core/internal/infrastructure/edastore"
)
// toolCallWriter is the edastore surface the projection writes through. Kept
// narrow so a test can fail it without touching the real store.
type toolCallWriter interface {
InsertToolCall(ctx context.Context, tc edastore.ToolCall) error
}
// toolCallProjectingTaskStore decorates the State Store's task store so every
// persisted tool_call event also lands in the tool_calls collection on the
// event-capture store, which this same process owns. The task event log stays
// the source of truth; the collection is the queryable transcript of it.
//
// A projection failure is NEVER returned: event persistence is load-bearing,
// the collection is observability, and failing a task write because its
// transcript copy failed would trade the fact for its shadow. The failure is
// instead counted and logged with the running count, so it is visible without
// ever changing InsertEvent's outcome.
type toolCallProjectingTaskStore struct {
storecontract.TaskStore
toolCalls toolCallWriter
log *slog.Logger
projectionFailures atomic.Int64
}
func newToolCallProjectingTaskStore(inner storecontract.TaskStore, toolCalls toolCallWriter, log *slog.Logger) *toolCallProjectingTaskStore {
if log == nil {
log = slog.Default()
}
return &toolCallProjectingTaskStore{TaskStore: inner, toolCalls: toolCalls, log: log}
}
// toolCallProjectionFailures reports how many tool_call projections have been
// dropped since this process started. Named and exported to the test surface
// rather than buried in a log field alone: a silent swallow is the bug this
// decorator exists not to have.
func (s *toolCallProjectingTaskStore) toolCallProjectionFailures() int64 {
return s.projectionFailures.Load()
}
func (s *toolCallProjectingTaskStore) InsertEvent(ctx context.Context, e events.Event) (int64, error) {
id, err := s.TaskStore.InsertEvent(ctx, e)
if err != nil || e.Kind != events.KindToolCall {
return id, err
}
if perr := s.toolCalls.InsertToolCall(ctx, toolCallFromEvent(e)); perr != nil {
failures := s.projectionFailures.Add(1)
s.log.Error("tool_call projection failed; the event persisted but the tool_calls row did not",
"err", perr, "task_id", e.TaskID, "attempt", e.Attempt,
"tool", e.Data["tool"], "projection_failures", failures)
}
return id, nil
}
// toolCallFromEvent adapts a tool_call event to the existing tool_calls
// collection. The event carries the tool name and the failure flag in data and
// the one-line outcome in detail: a succeeded call's summary is its result, a
// failed call's summary is its error. The collection's args and duration_ms
// fields stay unwritten -- the event reports neither -- so they are schema
// reserved for a producer that one day reports them, not promises this
// projection makes.
func toolCallFromEvent(e events.Event) edastore.ToolCall {
tool, _ := e.Data["tool"].(string)
failed, _ := e.Data["failed"].(bool)
tc := edastore.ToolCall{
TaskID: e.TaskID,
Attempt: e.Attempt,
Tool: tool,
CalledAt: e.At,
}
if failed {
tc.Error = e.Detail
} else {
tc.Result = e.Detail
}
return tc
}
@@ -0,0 +1,192 @@
package archied
import (
"bytes"
"context"
"errors"
"log/slog"
"strings"
"testing"
"time"
"github.com/samcharles93/archie-core/internal/events"
"github.com/samcharles93/archie-core/internal/infrastructure/edastore"
"github.com/samcharles93/archie-core/internal/infrastructure/staterpc"
"github.com/samcharles93/archie-core/internal/store"
)
func toolCallEvent(taskID int64, attempt int) events.Event {
return events.Event{
Kind: events.KindToolCall,
TaskID: taskID,
Attempt: attempt,
Stage: "implement",
Detail: "all checks passed",
Data: map[string]any{"tool": "shell", "failed": false},
At: time.Now().UTC(),
Workflow: "tdd",
}
}
// TestInsertEventProjectsToolCall pins the projection (test a): one tool_call
// event through the decorated store persists the event AND exactly one
// tool_calls row, with the row's fields taken from the event -- the tool name
// from data, the output summary in result for a succeeded call.
func TestInsertEventProjectsToolCall(t *testing.T) {
st := store.OpenTest(t)
eda := edastore.OpenTest(t)
ts := newToolCallProjectingTaskStore(st, eda, slog.Default())
id, err := ts.InsertEvent(t.Context(), toolCallEvent(42, 2))
if err != nil {
t.Fatalf("InsertEvent() error = %v", err)
}
if id == 0 {
t.Fatal("InsertEvent() returned id 0; the event itself must still persist")
}
rows, err := eda.TaskToolCalls(t.Context(), 42)
if err != nil {
t.Fatalf("TaskToolCalls() error = %v", err)
}
if len(rows) != 1 {
t.Fatalf("TaskToolCalls() returned %d rows, want exactly one per tool_call event: %+v", len(rows), rows)
}
row := rows[0]
if row.TaskID != 42 || row.Attempt != 2 {
t.Errorf("row task/attempt = %d/%d, want 42/2", row.TaskID, row.Attempt)
}
if row.Tool != "shell" {
t.Errorf("row tool = %q, want \"shell\" from the event's data", row.Tool)
}
if row.Result != "all checks passed" {
t.Errorf("row result = %q, want the event detail of a succeeded call", row.Result)
}
if row.Error != "" {
t.Errorf("row error = %q, want empty for a succeeded call", row.Error)
}
if row.CalledAt.IsZero() {
t.Error("row called_at is zero; it must carry the event time")
}
}
// TestInsertEventProjectsFailedToolCall pins the failure column: a tool_call
// event whose call failed stores its detail under error, not result, so the
// transcript can distinguish the two without re-parsing text.
func TestInsertEventProjectsFailedToolCall(t *testing.T) {
st := store.OpenTest(t)
eda := edastore.OpenTest(t)
ts := newToolCallProjectingTaskStore(st, eda, slog.Default())
e := toolCallEvent(42, 2)
e.Detail = "error: no such file"
e.Data = map[string]any{"tool": "read_file", "failed": true}
if _, err := ts.InsertEvent(t.Context(), e); err != nil {
t.Fatalf("InsertEvent() error = %v", err)
}
rows, err := eda.TaskToolCalls(t.Context(), 42)
if err != nil {
t.Fatalf("TaskToolCalls() error = %v", err)
}
if len(rows) != 1 {
t.Fatalf("TaskToolCalls() returned %d rows, want 1", len(rows))
}
if rows[0].Error != "error: no such file" {
t.Errorf("row error = %q, want the failed call's detail", rows[0].Error)
}
if rows[0].Result != "" {
t.Errorf("row result = %q, want empty for a failed call", rows[0].Result)
}
}
// TestInsertEventLeavesOtherKindsUnprojected pins the kind gate: only
// tool_call events reach the collection; the task timeline's other kinds must
// not grow tool_calls rows.
func TestInsertEventLeavesOtherKindsUnprojected(t *testing.T) {
st := store.OpenTest(t)
eda := edastore.OpenTest(t)
ts := newToolCallProjectingTaskStore(st, eda, slog.Default())
if _, err := ts.InsertEvent(t.Context(), events.Event{
Kind: events.KindStageFinish, TaskID: 42, Attempt: 2,
Data: map[string]any{"duration_ms": 12.0},
}); err != nil {
t.Fatalf("InsertEvent() error = %v", err)
}
rows, err := eda.TaskToolCalls(t.Context(), 42)
if err != nil {
t.Fatalf("TaskToolCalls() error = %v", err)
}
if len(rows) != 0 {
t.Fatalf("TaskToolCalls() returned %d rows for a stage_finish event, want 0", len(rows))
}
}
// failingToolCallWriter stands in for a broken PocketBase side, so the
// never-returned-failure contract can be tested without sabotaging the real
// store.
type failingToolCallWriter struct{ err error }
func (f failingToolCallWriter) InsertToolCall(context.Context, edastore.ToolCall) error {
return f.err
}
// TestInsertEventSucceedsWhenProjectionFails pins the load-bearing half of the
// contract: a tool_calls write failure is never returned from InsertEvent --
// event persistence is the contract, the projection is observability -- and
// the failure is recorded, not swallowed silently.
func TestInsertEventSucceedsWhenProjectionFails(t *testing.T) {
st := store.OpenTest(t)
var buf bytes.Buffer
ts := newToolCallProjectingTaskStore(st, failingToolCallWriter{
err: errors.New("disk on fire"),
}, slog.New(slog.NewTextHandler(&buf, nil)))
id, err := ts.InsertEvent(t.Context(), toolCallEvent(42, 2))
if err != nil {
t.Fatalf("InsertEvent() error = %v; a projection failure must never fail the event write", err)
}
if id == 0 {
t.Fatal("InsertEvent() returned id 0; the event must still persist")
}
if got := ts.toolCallProjectionFailures(); got != 1 {
t.Errorf("toolCallProjectionFailures() = %d, want 1: the failure must be counted, not swallowed", got)
}
if !strings.Contains(buf.String(), "disk on fire") {
t.Errorf("log output %q does not carry the projection failure; it was swallowed silently", buf.String())
}
// The event row is what the whole surface exists for -- it must be there.
persisted, err := st.TaskEvents(t.Context(), 42)
if err != nil {
t.Fatalf("TaskEvents() error = %v", err)
}
if len(persisted) != 1 {
t.Fatalf("TaskEvents() returned %d events, want 1: the event persisted despite the projection failure", len(persisted))
}
}
// TestStateStoreDepsProjectToolCalls pins the wire-in: with both stores open,
// the composition serves Tasks as the projecting decorator; with no
// event-capture store, Tasks is passed through untouched rather than wrapped
// around a nil writer.
func TestStateStoreDepsProjectToolCalls(t *testing.T) {
st := store.OpenTest(t)
eda := edastore.OpenTest(t)
b := newBootstrap()
b.st = st
b.eda = eda
deps := b.stateStoreDeps(&staterpc.TaskGrants{})
if _, ok := deps.Tasks.(*toolCallProjectingTaskStore); !ok {
t.Fatalf("deps.Tasks = %T, want the tool_call projecting decorator", deps.Tasks)
}
plain := newBootstrap()
plain.st = st
plainDeps := plain.stateStoreDeps(&staterpc.TaskGrants{})
if _, ok := plainDeps.Tasks.(*toolCallProjectingTaskStore); ok {
t.Fatal("deps.Tasks is decorated with no event-capture store on the boot; the projection would write through a nil writer")
}
}
@@ -13,6 +13,7 @@ import (
"google.golang.org/grpc"
"github.com/samcharles93/archie-core/internal/infrastructure/edastore"
"github.com/samcharles93/archie-core/internal/infrastructure/staterpc"
"github.com/samcharles93/archie-core/internal/logging"
"github.com/samcharles93/archie-core/internal/store"
@@ -165,8 +166,9 @@ func composeUIProcess(t *testing.T) (*webui.Server, int64) {
logs := logging.NewTaskRegistry(filepath.Join(t.TempDir(), "logs", "tasks"), logging.NewFeed(10), logging.TaskSinkOptions{})
target, stop := serveGRPC(t, func(r grpc.ServiceRegistrar) {
eda := edastore.OpenTest(t)
staterpc.RegisterServer(r, staterpc.Deps{
Tasks: st, Captures: st, BindingDispatcher: st, ConfigSnapshots: st,
Tasks: st, Captures: eda, BindingDispatcher: eda, ConfigSnapshots: st,
TaskLogs: logs, Log: slog.New(slog.DiscardHandler),
})
})
+3 -1
View File
@@ -21,6 +21,7 @@ import (
"github.com/samcharles93/archie-core/internal/domain/taskactions"
"github.com/samcharles93/archie-core/internal/events"
"github.com/samcharles93/archie-core/internal/gateway"
"github.com/samcharles93/archie-core/internal/infrastructure/edastore"
"github.com/samcharles93/archie-core/internal/infrastructure/gatewayrpc"
"github.com/samcharles93/archie-core/internal/infrastructure/staterpc"
"github.com/samcharles93/archie-core/internal/store"
@@ -151,7 +152,8 @@ func TestUIServesDashboardAgainstRemoteContracts(t *testing.T) {
}
stateTarget, stopState := serveGRPC(t, func(r grpc.ServiceRegistrar) {
staterpc.RegisterServer(r, staterpc.Deps{Tasks: st, Captures: st, BindingDispatcher: st, ConfigSnapshots: st, Log: slog.New(slog.DiscardHandler)})
eda := edastore.OpenTest(t)
staterpc.RegisterServer(r, staterpc.Deps{Tasks: st, Captures: eda, BindingDispatcher: eda, ConfigSnapshots: st, Log: slog.New(slog.DiscardHandler)})
})
defer stopState()
chat := &fakeChat{sessions: []gateway.SessionContext{
+3 -1
View File
@@ -13,6 +13,7 @@ import (
"google.golang.org/grpc"
"github.com/samcharles93/archie-core/internal/infrastructure/edastore"
"github.com/samcharles93/archie-core/internal/infrastructure/staterpc"
"github.com/samcharles93/archie-core/internal/logging"
"github.com/samcharles93/archie-core/internal/store"
@@ -178,8 +179,9 @@ func composeUIProcessWithLog(t *testing.T) (*webui.Server, int64, int) {
}
target, stop := serveGRPC(t, func(r grpc.ServiceRegistrar) {
eda := edastore.OpenTest(t)
staterpc.RegisterServer(r, staterpc.Deps{
Tasks: st, Captures: st, BindingDispatcher: st, ConfigSnapshots: st,
Tasks: st, Captures: eda, BindingDispatcher: eda, ConfigSnapshots: st,
TaskLogs: logs, Log: slog.New(slog.DiscardHandler),
})
})
+5 -5
View File
@@ -11,9 +11,9 @@ import (
pb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1"
"github.com/samcharles93/archie-core/internal/domain/agent"
"github.com/samcharles93/archie-core/internal/domain/scheduling"
"github.com/samcharles93/archie-core/internal/domain/workflow"
"github.com/samcharles93/archie-core/internal/infrastructure/controlplanerpc"
"github.com/samcharles93/archie-core/internal/infrastructure/cronstore"
)
// Client is the control-plane client for every resource that does not resolve
@@ -25,7 +25,7 @@ import (
// Client is the control-plane client a process that serves the store uses. It
// embeds the Messaging Service's client -- the generic resource read path and
// the channel-settings projection -- and adds the resource-specific reads and
// watches, which need the workflow and cronstore engines that such a process
// watches, which need the workflow and scheduling engines that such a process
// already links (archie-core-1ng1).
type Client struct {
*controlplanerpc.Client
@@ -213,19 +213,19 @@ func sendUpdate[T any](ctx context.Context, out chan<- T, update T) bool {
}
}
func (c *Client) Schedules(ctx context.Context) ([]cronstore.JobSpec, int64, error) {
func (c *Client) Schedules(ctx context.Context) ([]scheduling.JobSpec, int64, error) {
response, err := c.rpc.Query(ctx, &pb.QueryRequest{Kind: SchedulesKind})
if err != nil {
return nil, 0, controlplanerpc.ClientError(err)
}
var jobs []cronstore.JobSpec
var jobs []scheduling.JobSpec
if err := json.Unmarshal(response.Resource.ValueJson, &jobs); err != nil {
return nil, 0, err
}
return jobs, response.Resource.Version, nil
}
func (c *Client) ReplaceSchedules(ctx context.Context, jobs []cronstore.JobSpec, expectedVersion int64, actor, source, requestID string) (int64, error) {
func (c *Client) ReplaceSchedules(ctx context.Context, jobs []scheduling.JobSpec, expectedVersion int64, actor, source, requestID string) (int64, error) {
value, err := json.Marshal(jobs)
if err != nil {
return 0, err
+5 -6
View File
@@ -8,7 +8,6 @@ import (
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/scheduling"
"github.com/samcharles93/archie-core/internal/infrastructure/cronstore"
)
const SchedulesKind = "schedules"
@@ -17,9 +16,9 @@ func scheduleDefinition() Definition {
return Definition{
Kind: SchedulesKind,
Title: "Schedules",
Document: []cronstore.JobSpec{},
Document: []scheduling.JobSpec{},
ApplyMode: "live",
Seed: func(config.Config) any { return []cronstore.JobSpec{} },
Seed: func(config.Config) any { return []scheduling.JobSpec{} },
Validate: func(input []byte) error {
return validateAs(input, validateSchedules)
},
@@ -27,7 +26,7 @@ func scheduleDefinition() Definition {
}
}
func validateSchedules(jobs []cronstore.JobSpec) error {
func validateSchedules(jobs []scheduling.JobSpec) error {
seen := make(map[string]struct{}, len(jobs))
for _, job := range jobs {
if strings.TrimSpace(job.ID) == "" {
@@ -37,7 +36,7 @@ func validateSchedules(jobs []cronstore.JobSpec) error {
return fmt.Errorf("duplicate schedule %q", job.ID)
}
seen[job.ID] = struct{}{}
if job.Kind != cronstore.KindWorkflow {
if job.Kind != scheduling.KindWorkflow {
return fmt.Errorf("schedule %q has unsupported kind %q", job.ID, job.Kind)
}
if err := job.Schedule.Validate(); err != nil {
@@ -51,7 +50,7 @@ func validateSchedules(jobs []cronstore.JobSpec) error {
}
func normalizeSchedules(input []byte) ([]byte, error) {
var jobs []cronstore.JobSpec
var jobs []scheduling.JobSpec
if err := json.Unmarshal(input, &jobs); err != nil {
return nil, err
}
+3 -3
View File
@@ -5,14 +5,14 @@ import (
"testing"
"time"
"github.com/samcharles93/archie-core/internal/infrastructure/cronstore"
"github.com/samcharles93/archie-core/internal/domain/scheduling"
)
func TestScheduleDefinitionComputesFirstRunAndRejectsDuplicateIDs(t *testing.T) {
t.Parallel()
definition := scheduleDefinition()
jobs := []cronstore.JobSpec{{ID: "daily", Kind: cronstore.KindWorkflow, Schedule: cronstore.Schedule{Kind: cronstore.ScheduleInterval, Interval: cronstore.Duration(time.Hour)}}}
jobs := []scheduling.JobSpec{{ID: "daily", Kind: scheduling.KindWorkflow, Schedule: scheduling.Schedule{Kind: scheduling.ScheduleInterval, Interval: scheduling.Duration(time.Hour)}}}
input, err := json.Marshal(jobs)
if err != nil {
t.Fatal(err)
@@ -21,7 +21,7 @@ func TestScheduleDefinitionComputesFirstRunAndRejectsDuplicateIDs(t *testing.T)
if err != nil {
t.Fatal(err)
}
var normalized []cronstore.JobSpec
var normalized []scheduling.JobSpec
if err := json.Unmarshal(got, &normalized); err != nil {
t.Fatal(err)
}
+2 -2
View File
@@ -17,7 +17,7 @@ const bareObjectSchema = `{"type":"object"}`
var timeType = reflect.TypeFor[time.Time]()
// stdDuration is the marker this tree's string-form duration types satisfy:
// config.Duration, channelDuration and cronstore.Duration each expose the
// config.Duration, channelDuration and scheduling.Duration each expose the
// standard duration for arithmetic.
var stdDuration = reflect.TypeOf((*interface{ Std() time.Duration })(nil)).Elem()
@@ -28,7 +28,7 @@ var stdDuration = reflect.TypeOf((*interface{ Std() time.Duration })(nil)).Elem(
// stale the moment a fourth duration type appears and the failure is silent in
// the worst direction: the field derives as an integer and a client renders a
// number box for a duration. That is exactly what the enumerated version of this
// function did to cronstore.Duration when the schedules interval became one.
// function did to scheduling.Duration when the schedules interval became one.
func durationLike(t reflect.Type) bool {
if !t.Implements(stdDuration) {
return false
+18 -2
View File
@@ -533,8 +533,10 @@ type Config struct {
// Tools holds MCP server and tool policy configuration (from config.tools.yaml).
Tools ToolsConfig `toml:"tools" yaml:"tools"`
// Indexing locates the workspace codesearch index.
Indexing IndexingConfig `toml:"indexing" yaml:"indexing"`
// Artifacts configures publishing artifacts to the collaborative editor.
// An empty BaseURL disables the sender entirely.
Artifacts ArtifactsConfig `toml:"artifacts" yaml:"artifacts"`
// Identities declares multi-identity configurations. When non-empty,
// each identity runs its own poll loop with its own forge client,
@@ -559,6 +561,20 @@ type Config struct {
Extra map[string]any `toml:"-" yaml:"-" json:"extra,omitempty"`
}
// ArtifactsConfig locates the collaborative editor that receives artifacts.
// An absent section is valid and disables publishing: the capability degrades
// to a log line rather than stopping the daemon.
type ArtifactsConfig struct {
// BaseURL is the editor origin, e.g. https://offloaded.dev. Empty
// disables artifact publishing.
BaseURL string `toml:"base_url" yaml:"base_url"`
// Token is the service credential the editor's ingest route requires.
Token SecretRef `toml:"token" yaml:"token"`
// TokenEnv names the environment variable holding the token when Token
// is unset. Defaults to WORKSPACE_INGEST_TOKEN.
TokenEnv string `toml:"token_env" yaml:"token_env"`
}
// IdentityConfig is a per-identity configuration subset. Each identity
// gets its own poll loop goroutine with isolated forge, repo, model,
// and dispatch configuration.
-29
View File
@@ -1,29 +0,0 @@
package config
import "path/filepath"
// IndexingConfig locates the workspace codesearch index.
//
// The index is a large, fully rebuildable artifact, so both paths are
// settable to allow putting it on different storage from the task work tree.
type IndexingConfig struct {
// IndexDir holds the codesearch sidecar files.
IndexDir string `toml:"index_dir" yaml:"index_dir" json:"index_dir,omitempty"`
// DBPath is the SQLite database holding index lifecycle metadata.
DBPath string `toml:"db_path" yaml:"db_path" json:"db_path,omitempty"`
}
// WithDefaults fills unset paths from the daemon's work directory.
//
// Deriving from workDir rather than a shared data home is deliberate: two
// archied instances run on one host, each with its own work_dir, so this
// keeps their indexes separate without either having to configure anything.
func (c IndexingConfig) WithDefaults(workDir string) IndexingConfig {
if c.IndexDir == "" {
c.IndexDir = filepath.Join(workDir, "indexes")
}
if c.DBPath == "" {
c.DBPath = filepath.Join(workDir, "workspace-indexes.db")
}
return c
}
File diff suppressed because it is too large. Load diff
@@ -37,9 +37,13 @@ const (
StateStoreService_Transition_FullMethodName = "/state.v1.StateStoreService/Transition"
StateStoreService_Update_FullMethodName = "/state.v1.StateStoreService/Update"
StateStoreService_Requeue_FullMethodName = "/state.v1.StateStoreService/Requeue"
StateStoreService_ParkTask_FullMethodName = "/state.v1.StateStoreService/ParkTask"
StateStoreService_RecoverStale_FullMethodName = "/state.v1.StateStoreService/RecoverStale"
StateStoreService_ArchiveTask_FullMethodName = "/state.v1.StateStoreService/ArchiveTask"
StateStoreService_RetryTask_FullMethodName = "/state.v1.StateStoreService/RetryTask"
StateStoreService_BeginRemediation_FullMethodName = "/state.v1.StateStoreService/BeginRemediation"
StateStoreService_UpdateReviewPayload_FullMethodName = "/state.v1.StateStoreService/UpdateReviewPayload"
StateStoreService_SetReviewCursors_FullMethodName = "/state.v1.StateStoreService/SetReviewCursors"
StateStoreService_TaskByIssue_FullMethodName = "/state.v1.StateStoreService/TaskByIssue"
StateStoreService_OpenTaskByPR_FullMethodName = "/state.v1.StateStoreService/OpenTaskByPR"
StateStoreService_TaskByID_FullMethodName = "/state.v1.StateStoreService/TaskByID"
@@ -120,10 +124,14 @@ type StateStoreServiceClient interface {
Transition(ctx context.Context, in *TransitionRequest, opts ...grpc.CallOption) (*TransitionResponse, error)
Update(ctx context.Context, in *UpdateRequest, opts ...grpc.CallOption) (*UpdateResponse, error)
Requeue(ctx context.Context, in *RequeueRequest, opts ...grpc.CallOption) (*RequeueResponse, error)
ParkTask(ctx context.Context, in *ParkTaskRequest, opts ...grpc.CallOption) (*ParkTaskResponse, error)
RecoverStale(ctx context.Context, in *RecoverStaleRequest, opts ...grpc.CallOption) (*RecoverStaleResponse, error)
// Archive / Retry
ArchiveTask(ctx context.Context, in *ArchiveTaskRequest, opts ...grpc.CallOption) (*ArchiveTaskResponse, error)
RetryTask(ctx context.Context, in *RetryTaskRequest, opts ...grpc.CallOption) (*RetryTaskResponse, error)
BeginRemediation(ctx context.Context, in *BeginRemediationRequest, opts ...grpc.CallOption) (*BeginRemediationResponse, error)
UpdateReviewPayload(ctx context.Context, in *UpdateReviewPayloadRequest, opts ...grpc.CallOption) (*UpdateReviewPayloadResponse, error)
SetReviewCursors(ctx context.Context, in *SetReviewCursorsRequest, opts ...grpc.CallOption) (*SetReviewCursorsResponse, error)
// Queries
TaskByIssue(ctx context.Context, in *TaskByIssueRequest, opts ...grpc.CallOption) (*TaskByIssueResponse, error)
OpenTaskByPR(ctx context.Context, in *OpenTaskByPRRequest, opts ...grpc.CallOption) (*OpenTaskByPRResponse, error)
@@ -402,6 +410,16 @@ func (c *stateStoreServiceClient) Requeue(ctx context.Context, in *RequeueReques
return out, nil
}
func (c *stateStoreServiceClient) ParkTask(ctx context.Context, in *ParkTaskRequest, opts ...grpc.CallOption) (*ParkTaskResponse, error) {
cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
out := new(ParkTaskResponse)
err := c.cc.Invoke(ctx, StateStoreService_ParkTask_FullMethodName, in, out, cOpts...)
if err != nil {
return nil, err
}
return out, nil
}
func (c *stateStoreServiceClient) RecoverStale(ctx context.Context, in *RecoverStaleRequest, opts ...grpc.CallOption) (*RecoverStaleResponse, error) {
cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
out := new(RecoverStaleResponse)
@@ -432,6 +450,36 @@ func (c *stateStoreServiceClient) RetryTask(ctx context.Context, in *RetryTaskRe
return out, nil
}
func (c *stateStoreServiceClient) BeginRemediation(ctx context.Context, in *BeginRemediationRequest, opts ...grpc.CallOption) (*BeginRemediationResponse, error) {
cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
out := new(BeginRemediationResponse)
err := c.cc.Invoke(ctx, StateStoreService_BeginRemediation_FullMethodName, in, out, cOpts...)
if err != nil {
return nil, err
}
return out, nil
}
func (c *stateStoreServiceClient) UpdateReviewPayload(ctx context.Context, in *UpdateReviewPayloadRequest, opts ...grpc.CallOption) (*UpdateReviewPayloadResponse, error) {
cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
out := new(UpdateReviewPayloadResponse)
err := c.cc.Invoke(ctx, StateStoreService_UpdateReviewPayload_FullMethodName, in, out, cOpts...)
if err != nil {
return nil, err
}
return out, nil
}
func (c *stateStoreServiceClient) SetReviewCursors(ctx context.Context, in *SetReviewCursorsRequest, opts ...grpc.CallOption) (*SetReviewCursorsResponse, error) {
cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
out := new(SetReviewCursorsResponse)
err := c.cc.Invoke(ctx, StateStoreService_SetReviewCursors_FullMethodName, in, out, cOpts...)
if err != nil {
return nil, err
}
return out, nil
}
func (c *stateStoreServiceClient) TaskByIssue(ctx context.Context, in *TaskByIssueRequest, opts ...grpc.CallOption) (*TaskByIssueResponse, error) {
cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
out := new(TaskByIssueResponse)
@@ -917,10 +965,14 @@ type StateStoreServiceServer interface {
Transition(context.Context, *TransitionRequest) (*TransitionResponse, error)
Update(context.Context, *UpdateRequest) (*UpdateResponse, error)
Requeue(context.Context, *RequeueRequest) (*RequeueResponse, error)
ParkTask(context.Context, *ParkTaskRequest) (*ParkTaskResponse, error)
RecoverStale(context.Context, *RecoverStaleRequest) (*RecoverStaleResponse, error)
// Archive / Retry
ArchiveTask(context.Context, *ArchiveTaskRequest) (*ArchiveTaskResponse, error)
RetryTask(context.Context, *RetryTaskRequest) (*RetryTaskResponse, error)
BeginRemediation(context.Context, *BeginRemediationRequest) (*BeginRemediationResponse, error)
UpdateReviewPayload(context.Context, *UpdateReviewPayloadRequest) (*UpdateReviewPayloadResponse, error)
SetReviewCursors(context.Context, *SetReviewCursorsRequest) (*SetReviewCursorsResponse, error)
// Queries
TaskByIssue(context.Context, *TaskByIssueRequest) (*TaskByIssueResponse, error)
OpenTaskByPR(context.Context, *OpenTaskByPRRequest) (*OpenTaskByPRResponse, error)
@@ -1073,6 +1125,9 @@ func (UnimplementedStateStoreServiceServer) Update(context.Context, *UpdateReque
func (UnimplementedStateStoreServiceServer) Requeue(context.Context, *RequeueRequest) (*RequeueResponse, error) {
return nil, status.Error(codes.Unimplemented, "method Requeue not implemented")
}
func (UnimplementedStateStoreServiceServer) ParkTask(context.Context, *ParkTaskRequest) (*ParkTaskResponse, error) {
return nil, status.Error(codes.Unimplemented, "method ParkTask not implemented")
}
func (UnimplementedStateStoreServiceServer) RecoverStale(context.Context, *RecoverStaleRequest) (*RecoverStaleResponse, error) {
return nil, status.Error(codes.Unimplemented, "method RecoverStale not implemented")
}
@@ -1082,6 +1137,15 @@ func (UnimplementedStateStoreServiceServer) ArchiveTask(context.Context, *Archiv
func (UnimplementedStateStoreServiceServer) RetryTask(context.Context, *RetryTaskRequest) (*RetryTaskResponse, error) {
return nil, status.Error(codes.Unimplemented, "method RetryTask not implemented")
}
func (UnimplementedStateStoreServiceServer) BeginRemediation(context.Context, *BeginRemediationRequest) (*BeginRemediationResponse, error) {
return nil, status.Error(codes.Unimplemented, "method BeginRemediation not implemented")
}
func (UnimplementedStateStoreServiceServer) UpdateReviewPayload(context.Context, *UpdateReviewPayloadRequest) (*UpdateReviewPayloadResponse, error) {
return nil, status.Error(codes.Unimplemented, "method UpdateReviewPayload not implemented")
}
func (UnimplementedStateStoreServiceServer) SetReviewCursors(context.Context, *SetReviewCursorsRequest) (*SetReviewCursorsResponse, error) {
return nil, status.Error(codes.Unimplemented, "method SetReviewCursors not implemented")
}
func (UnimplementedStateStoreServiceServer) TaskByIssue(context.Context, *TaskByIssueRequest) (*TaskByIssueResponse, error) {
return nil, status.Error(codes.Unimplemented, "method TaskByIssue not implemented")
}
@@ -1553,6 +1617,24 @@ func _StateStoreService_Requeue_Handler(srv interface{}, ctx context.Context, de
return interceptor(ctx, in, info, handler)
}
func _StateStoreService_ParkTask_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
in := new(ParkTaskRequest)
if err := dec(in); err != nil {
return nil, err
}
if interceptor == nil {
return srv.(StateStoreServiceServer).ParkTask(ctx, in)
}
info := &grpc.UnaryServerInfo{
Server: srv,
FullMethod: StateStoreService_ParkTask_FullMethodName,
}
handler := func(ctx context.Context, req interface{}) (interface{}, error) {
return srv.(StateStoreServiceServer).ParkTask(ctx, req.(*ParkTaskRequest))
}
return interceptor(ctx, in, info, handler)
}
func _StateStoreService_RecoverStale_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
in := new(RecoverStaleRequest)
if err := dec(in); err != nil {
@@ -1607,6 +1689,60 @@ func _StateStoreService_RetryTask_Handler(srv interface{}, ctx context.Context,
return interceptor(ctx, in, info, handler)
}
func _StateStoreService_BeginRemediation_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
in := new(BeginRemediationRequest)
if err := dec(in); err != nil {
return nil, err
}
if interceptor == nil {
return srv.(StateStoreServiceServer).BeginRemediation(ctx, in)
}
info := &grpc.UnaryServerInfo{
Server: srv,
FullMethod: StateStoreService_BeginRemediation_FullMethodName,
}
handler := func(ctx context.Context, req interface{}) (interface{}, error) {
return srv.(StateStoreServiceServer).BeginRemediation(ctx, req.(*BeginRemediationRequest))
}
return interceptor(ctx, in, info, handler)
}
func _StateStoreService_UpdateReviewPayload_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
in := new(UpdateReviewPayloadRequest)
if err := dec(in); err != nil {
return nil, err
}
if interceptor == nil {
return srv.(StateStoreServiceServer).UpdateReviewPayload(ctx, in)
}
info := &grpc.UnaryServerInfo{
Server: srv,
FullMethod: StateStoreService_UpdateReviewPayload_FullMethodName,
}
handler := func(ctx context.Context, req interface{}) (interface{}, error) {
return srv.(StateStoreServiceServer).UpdateReviewPayload(ctx, req.(*UpdateReviewPayloadRequest))
}
return interceptor(ctx, in, info, handler)
}
func _StateStoreService_SetReviewCursors_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
in := new(SetReviewCursorsRequest)
if err := dec(in); err != nil {
return nil, err
}
if interceptor == nil {
return srv.(StateStoreServiceServer).SetReviewCursors(ctx, in)
}
info := &grpc.UnaryServerInfo{
Server: srv,
FullMethod: StateStoreService_SetReviewCursors_FullMethodName,
}
handler := func(ctx context.Context, req interface{}) (interface{}, error) {
return srv.(StateStoreServiceServer).SetReviewCursors(ctx, req.(*SetReviewCursorsRequest))
}
return interceptor(ctx, in, info, handler)
}
func _StateStoreService_TaskByIssue_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
in := new(TaskByIssueRequest)
if err := dec(in); err != nil {
@@ -2421,6 +2557,10 @@ var StateStoreService_ServiceDesc = grpc.ServiceDesc{
MethodName: "Requeue",
Handler: _StateStoreService_Requeue_Handler,
},
{
MethodName: "ParkTask",
Handler: _StateStoreService_ParkTask_Handler,
},
{
MethodName: "RecoverStale",
Handler: _StateStoreService_RecoverStale_Handler,
@@ -2433,6 +2573,18 @@ var StateStoreService_ServiceDesc = grpc.ServiceDesc{
MethodName: "RetryTask",
Handler: _StateStoreService_RetryTask_Handler,
},
{
MethodName: "BeginRemediation",
Handler: _StateStoreService_BeginRemediation_Handler,
},
{
MethodName: "UpdateReviewPayload",
Handler: _StateStoreService_UpdateReviewPayload_Handler,
},
{
MethodName: "SetReviewCursors",
Handler: _StateStoreService_SetReviewCursors_Handler,
},
{
MethodName: "TaskByIssue",
Handler: _StateStoreService_TaskByIssue_Handler,
+149 -43
View File
@@ -25,6 +25,7 @@ import (
"github.com/samcharles93/archie-core/internal/domain/mapping"
"github.com/samcharles93/archie-core/internal/domain/storecontract"
"github.com/samcharles93/archie-core/internal/domain/workflow"
workflowtask "github.com/samcharles93/archie-core/internal/domain/workflow/task"
"github.com/samcharles93/archie-core/internal/domain/workintake"
"github.com/samcharles93/archie-core/internal/eventbus"
"github.com/samcharles93/archie-core/internal/events"
@@ -34,6 +35,7 @@ import (
"github.com/samcharles93/archie-core/internal/plugin"
"github.com/samcharles93/archie-core/internal/storage"
"github.com/samcharles93/archie-core/internal/taskrun"
"github.com/samcharles93/archie-core/internal/taskstate"
"github.com/samcharles93/archie-core/internal/tools"
"github.com/samcharles93/archie-core/internal/worktree"
)
@@ -132,7 +134,20 @@ type Daemon struct {
// NATS startup is mandatory (there is no broker-off execution mode), so
// production composition always sets it. Nil appears only in tests and
// is handled fail-closed at the publish/run sites.
Tasks TaskBus
Tasks TaskBus
// reactionConsumer is built lazily by drainReactions and kept for its
// lifetime drop counter.
reactionConsumer *reactionConsumer
// reactionPublisher is built lazily by scanPRReviews; an indirection
// only so tests can swap the delivery without the bus.
reactionPublisher ReactionPublisher
// Reactions pulls the review-reaction fan-out stream
// (docs/prds/pr-review-remediation.md). Each cycle it is drained into
// queued remediate runs before the task drain, so a reaction can be
// claimed in the same pass that carried it. Optional: nil disables the
// reaction consumer (tests, or a deployment without the reaction
// stream).
Reactions ReactionSource
WorktreeGrants WorktreeGrantIssuer
// StateStoreGrants issues per-task State Store credentials for container
// env (see containerEnv). Required whenever ConnectedStateStore.URL is
@@ -486,7 +501,9 @@ func (d *Daemon) pollForIdentity(ctx context.Context, id *IdentityRunner) {
func (d *Daemon) maintainAndDrain(ctx context.Context) {
d.cleanupExpiredStorage(ctx)
d.reconcilePRs(ctx)
d.scanPRReviews(ctx)
d.dispatchBindings(ctx)
d.drainReactions(ctx)
if d.Tasks != nil {
d.drainNATS(ctx)
}
@@ -560,7 +577,9 @@ func (d *Daemon) Cycle(ctx context.Context) {
d.cleanupExpiredStorage(ctx)
d.poll(ctx)
d.reconcilePRs(ctx)
d.scanPRReviews(ctx)
d.dispatchBindings(ctx)
d.drainReactions(ctx)
if d.Tasks != nil {
d.drainNATS(ctx)
}
@@ -678,7 +697,7 @@ func (d *Daemon) dispatchOneBinding(ctx context.Context, b binding.Binding, c st
if hasBlockingFailure(m.Fields, failures) {
_, _ = d.Store.InsertEvent(ctx, events.Event{
Kind: "binding_dispatch_failure",
Detail: fmt.Sprintf("binding %d (capture %d): required field failed", b.ID, c.ID),
Detail: fmt.Sprintf("binding %q (capture %q): required field failed", b.ID, c.ID),
Data: map[string]any{
"binding_id": b.ID,
"binding_version": b.Version,
@@ -746,7 +765,7 @@ func hasBlockingFailure(fields []mapping.Field, failures []mapping.Failure) bool
// provenance to hand back to the operator.
func renderBindingBody(values map[string]any, c storecontract.CapturedEvent) string {
if len(values) == 0 {
return fmt.Sprintf("(no fields resolved from capture %d)", c.ID)
return fmt.Sprintf("(no fields resolved from capture %q)", c.ID)
}
parts := make([]string, 0, len(values))
for k, v := range values {
@@ -778,6 +797,40 @@ func (d *Daemon) resolveBindingRepo(b binding.Binding) (string, string, bool) {
return "", "", false
}
// drainReactions turns available review reactions into queued remediate
// runs. It runs before the task drain so a reaction queued in this pass can
// be claimed by it; the consumer is built lazily once, so its drop counter
// spans the process lifetime.
func (d *Daemon) drainReactions(ctx context.Context) {
if d.Reactions == nil || d.Store == nil {
return
}
if d.reactionConsumer == nil {
d.reactionConsumer = newReactionConsumer(
// The store's owned-PR lookup is the authorization boundary: a
// reaction only ever causes work against a PR archie opened and
// still owns (pr-review-remediation.md decision 3).
d.Store,
d.Store,
d.botUserForTask,
d.Log,
)
}
if _, err := d.reactionConsumer.drain(ctx, d.Reactions, maxReactionsPerCycle); err != nil {
d.Log.Error("reaction drain failed", "err", err)
}
}
// botUserForTask resolves the bot login that owns task, so the reaction
// consumer can exclude Archie's own comments. Identity-derived for
// multi-identity deployments, the global forge bot user otherwise.
func (d *Daemon) botUserForTask(task *workflowtask.Task) string {
if runner := d.identityFor(task); runner != nil {
return runner.Cfg.BotUser
}
return d.Cfg.Get().BotUser
}
// drainNATS processes tasks from NATS, falling back to SQLite ClaimNext for
// requeued tasks (waiting_human approval, retry-parked) that didn't come
// through a NATS publish.
@@ -994,6 +1047,14 @@ func (d *Daemon) processNATSTask(ctx context.Context, msg eventbus.Message) {
return
}
if ok, reason, _ := d.identityMayAct(ctx, tm.Identity); !ok {
d.Log.Error("nats intake rejected: "+reason, "subject", msg.Subject())
if err := msg.Ack(); err != nil {
d.Log.Warn("ack failed", "err", err)
}
return
}
inserted, err := d.Store.EnqueueIssue(ctx, tm.Owner, tm.Repo, tm.Number, tm.Title, tm.Body, strings.Join(tm.Labels, ","), tm.Identity)
if err != nil {
d.Log.Error("nats enqueue failed", "err", err)
@@ -1126,39 +1187,18 @@ func (d *Daemon) process(ctx context.Context, task *workflow.Task) {
defer finished()
defer d.openTaskLog(task)()
if d.parkIfIdentityUnresolvable(ctx, task) {
return
}
trees := d.treesFor(task)
repo, ok := d.repoFor(task)
if !ok {
d.parkRunningTask(ctx, task.ID, "repo no longer in config")
d.parkRunningTask(ctx, task.ID, "repo no longer in config", taskstate.ParkTerminal)
return
}
if d.ContainerPool == nil {
const reason = "managed agent container pool is unavailable; refusing to run this task on the host"
d.Log.Error("task parked: managed worker unavailable", "task", task.ID,
"hint", "enable containers and make the archie-agent image available, then retry the task")
if err := d.Store.Transition(ctx, task.ID, workflow.StatusRunning, workflow.StatusParked, reason); err != nil {
d.Log.Warn("managed worker park transition failed", "task", task.ID, "err", err)
return
}
d.recordPark(ctx, task.ID, reason)
d.emit(events.Event{
Kind: events.KindParked, TaskID: task.ID, Attempt: task.Attempt,
Repo: repo.FullName(), Issue: task.IssueNumber, Detail: reason,
})
return
}
if d.Tasks == nil {
const reason = "agent task transport is unavailable; refusing to run this task on the host"
d.Log.Error("task parked: agent task transport unavailable", "task", task.ID)
if err := d.Store.Transition(ctx, task.ID, workflow.StatusRunning, workflow.StatusParked, reason); err != nil {
d.Log.Warn("agent task transport park transition failed", "task", task.ID, "err", err)
return
}
d.recordPark(ctx, task.ID, reason)
d.emit(events.Event{
Kind: events.KindParked, TaskID: task.ID, Attempt: task.Attempt,
Repo: repo.FullName(), Issue: task.IssueNumber, Detail: reason,
})
if d.ContainerPool == nil || d.Tasks == nil {
d.parkCapabilityUnavailable(ctx, task, repo)
return
}
@@ -1178,7 +1218,7 @@ func (d *Daemon) process(ctx context.Context, task *workflow.Task) {
_, branch, err = trees.Prepare(ctx, task.Owner, task.Repo, repo.BaseBranch(), task.IssueNumber, task.Title, task.Body, task.Labels)
if err != nil {
d.Log.Error("worktree prepare failed", "err", err)
d.parkRunningTask(ctx, task.ID, "worktree prepare failed: "+err.Error())
d.parkRunningTask(ctx, task.ID, "worktree prepare failed: "+err.Error(), taskstate.ParkTransient)
return
}
task.Branch = branch
@@ -1272,7 +1312,7 @@ func (d *Daemon) acquireTaskContainer(
) (*container.Container, func(), bool) {
park := func(reason string, err error) {
d.Log.Error(reason, "err", err)
d.parkRunningTask(ctx, task.ID, reason+": "+err.Error())
d.parkRunningTask(ctx, task.ID, reason+": "+err.Error(), taskstate.ParkTransient)
}
// Write task.json -- the container's boot-time brief.
@@ -1290,7 +1330,7 @@ func (d *Daemon) acquireTaskContainer(
// normal operation, Storage is always set when ContainerPool is set.
if d.Storage == nil {
d.Log.Error("storage backend is nil -- cannot acquire container")
d.parkRunningTask(ctx, task.ID, "storage backend not configured")
d.parkRunningTask(ctx, task.ID, "storage backend not configured", taskstate.ParkTransient)
return nil, nil, false
}
@@ -1343,9 +1383,38 @@ func (d *Daemon) acquireTaskContainer(
return ctr, revokeStateStoreGrant, true
}
// parkCapabilityUnavailable parks a task whose daemon-side capability is
// missing (container pool or task transport): both are environmental, so
// the park class is transient and the KindParked event carries the class
// for the dashboard. The reason distinguishes the two in logs and events.
func (d *Daemon) parkCapabilityUnavailable(ctx context.Context, task *workflow.Task, repo config.Repo) {
var reason string
if d.ContainerPool == nil {
reason = "managed agent container pool is unavailable; refusing to run this task on the host"
d.Log.Error("task parked: managed worker unavailable", "task", task.ID,
"hint", "enable containers and make the archie-agent image available, then retry the task")
} else {
reason = "agent task transport is unavailable; refusing to run this task on the host"
d.Log.Error("task parked: agent task transport unavailable", "task", task.ID)
}
if err := d.Store.ParkTask(ctx, task.ID, workflow.StatusRunning, reason, taskstate.ParkTransient); err != nil {
d.Log.Warn("capability park transition failed", "task", task.ID, "err", err)
return
}
d.recordPark(ctx, task.ID, reason)
d.emit(events.Event{
Kind: events.KindParked, TaskID: task.ID, Attempt: task.Attempt,
Repo: repo.FullName(), Issue: task.IssueNumber, Detail: reason,
Data: map[string]any{"park_class": taskstate.ParkTransient},
})
}
// parkRunningTask transitions a task from running to parked using a context
// detached from caller cancellation, with a bounded timeout.
//
// The park carries the caller's taskstate.ParkClass: every call site states
// what kind of intervention its park needs, and the store normalizes the
// class, so an unclassified caller cannot silently mislabel a park.
// When a task fails or is cancelled (e.g. via /stop or dashboard Stop), ctx is
// already cancelled. Writing terminal state using the cancelled ctx fails
// immediately in SQLite transactions and silently leaves the task row 'running'
@@ -1356,14 +1425,14 @@ func (d *Daemon) acquireTaskContainer(
// The transition remains guarded from StatusRunning: if the worker already
// recorded a terminal state over storerpc, storecontract.ErrStaleTransition is returned
// and ignored. Unexpected store errors are logged as warnings.
func (d *Daemon) parkRunningTask(ctx context.Context, taskID int64, reason string) {
func (d *Daemon) parkRunningTask(ctx context.Context, taskID int64, reason string, class taskstate.ParkClass) {
if d.Store == nil {
return
}
writeCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 10*time.Second)
defer cancel()
if err := d.Store.Transition(writeCtx, taskID, workflow.StatusRunning, workflow.StatusParked, reason); err != nil {
if err := d.Store.ParkTask(writeCtx, taskID, workflow.StatusRunning, reason, class); err != nil {
if !errors.Is(err, storecontract.ErrStaleTransition) {
d.Log.Warn("terminal park transition failed", "task", taskID, "reason", reason, "err", err)
}
@@ -1410,13 +1479,13 @@ func (d *Daemon) runViaAgent(ctx context.Context, task *workflow.Task, repo conf
if d.WorktreeGrants == nil {
const reason = "worktree publication grants are unavailable"
d.Log.Error(reason, "task", task.ID)
d.parkRunningTask(ctx, task.ID, reason)
d.parkRunningTask(ctx, task.ID, reason, taskstate.ParkTransient)
return
}
grant, revoke, err := d.WorktreeGrants.Issue(task)
if err != nil {
d.Log.Error("worktree publication grant failed", "task", task.ID, "err", err)
d.parkRunningTask(ctx, task.ID, "worktree publication grant failed: "+err.Error())
d.parkRunningTask(ctx, task.ID, "worktree publication grant failed: "+err.Error(), taskstate.ParkTransient)
return
}
defer revoke()
@@ -1425,7 +1494,7 @@ func (d *Daemon) runViaAgent(ctx context.Context, task *workflow.Task, repo conf
d.captureAttemptConfig(ctx, task, taskCfg)
if err := d.pinWorkflowDefinition(ctx, task); err != nil {
d.Log.Error("pin workflow definition failed", "task", task.ID, "err", err)
d.parkRunningTask(ctx, task.ID, "pin workflow definition: "+err.Error())
d.parkRunningTask(ctx, task.ID, "pin workflow definition: "+err.Error(), taskstate.ParkTransient)
return
}
req := taskrun.Request{
@@ -1442,26 +1511,26 @@ func (d *Daemon) runViaAgent(ctx context.Context, task *workflow.Task, repo conf
data, err := json.Marshal(req)
if err != nil {
d.Log.Error("taskrun encode failed", "task", task.ID, "err", err)
d.parkRunningTask(ctx, task.ID, "taskrun encode failed: "+err.Error())
d.parkRunningTask(ctx, task.ID, "taskrun encode failed: "+err.Error(), taskstate.ParkTransient)
return
}
reply, err := d.requestTaskRun(ctx, task.ID, data)
if err != nil {
d.Log.Error("taskrun request failed", "task", task.ID, "err", err)
d.parkRunningTask(ctx, task.ID, "taskrun request failed: "+err.Error())
d.parkRunningTask(ctx, task.ID, "taskrun request failed: "+err.Error(), taskstate.ParkTransient)
return
}
var resp taskrun.Response
if err := json.Unmarshal(reply, &resp); err != nil {
d.Log.Error("taskrun decode response failed", "task", task.ID, "err", err)
d.parkRunningTask(ctx, task.ID, "taskrun decode response failed: "+err.Error())
d.parkRunningTask(ctx, task.ID, "taskrun decode response failed: "+err.Error(), taskstate.ParkTransient)
return
}
if resp.Error != "" {
d.Log.Error("taskrun run failed", "task", task.ID, "err", resp.Error)
d.parkRunningTask(ctx, task.ID, "taskrun run failed: "+resp.Error)
d.parkRunningTask(ctx, task.ID, "taskrun run failed: "+resp.Error, taskstate.ParkTransient)
return
}
@@ -1770,6 +1839,43 @@ func (d *Daemon) identityFor(task *workflow.Task) *IdentityRunner {
return nil
}
// identityMayAct reports whether the identity a task carries may be acted on.
// A denial also carries the park class the task would need: a name that no
// longer resolves is fixable by re-adding the identity (transient), while a
// retired or deactivated identity is a deliberate operator state (terminal).
// An empty identity is the single-identity root and always may act. A
// non-empty identity must resolve to a configured runner and pass the
// lifecycle check; otherwise the returned reason says why it may not. This is
// the single task-side fail-closed point, mirroring identity.Resolve's
// credential-side behaviour: a task naming an identity archie no longer knows
// -- renamed, retired, or deleted in the control plane -- must park, never
// fall back to the root forge's credential.
func (d *Daemon) identityMayAct(ctx context.Context, name string) (bool, string, taskstate.ParkClass) {
if name == "" {
return true, "", ""
}
runner := d.identityFor(&workflow.Task{Identity: name})
if runner == nil {
return false, "identity " + name + " no longer resolves", taskstate.ParkTransient
}
if !d.identityActive(ctx, runner.ID) {
return false, "identity " + runner.Name + " may not act", taskstate.ParkTerminal
}
return true, "", ""
}
// parkIfIdentityUnresolvable parks task when its non-empty identity cannot be
// acted on, reporting whether it did. An empty identity is the root
// single-identity path and never parks here.
func (d *Daemon) parkIfIdentityUnresolvable(ctx context.Context, task *workflow.Task) bool {
ok, reason, class := d.identityMayAct(ctx, task.Identity)
if ok {
return false
}
d.parkRunningTask(ctx, task.ID, reason, class)
return true
}
func (d *Daemon) identityActive(ctx context.Context, id identity.IdentityID) bool {
if d.IdentityRepository == nil {
return true
+3 -2
View File
@@ -32,6 +32,7 @@ import (
"github.com/samcharles93/archie-core/internal/storage"
"github.com/samcharles93/archie-core/internal/store"
"github.com/samcharles93/archie-core/internal/taskrun"
"github.com/samcharles93/archie-core/internal/taskstate"
"github.com/samcharles93/archie-core/internal/worktree"
)
@@ -120,7 +121,7 @@ func TestParkRunningTaskRecordsItsReasonInTheTasksOwnLog(t *testing.T) {
defer closeLog()
const reason = "worktree prepare failed: checkout branch fix/42-x: reference not found"
d.parkRunningTask(ctx, task.ID, reason)
d.parkRunningTask(ctx, task.ID, reason, taskstate.ParkTransient)
page, err := d.TaskLogs.TaskLog(ctx, task.ID, task.Attempt, logging.Query{})
if err != nil {
@@ -166,7 +167,7 @@ func TestParkDoesNotRecordAParkThatLosesTheRace(t *testing.T) {
closeLog := d.openTaskLog(task)
defer closeLog()
d.parkRunningTask(ctx, task.ID, "worktree prepare failed: simulated")
d.parkRunningTask(ctx, task.ID, "worktree prepare failed: simulated", taskstate.ParkTransient)
page, err := d.TaskLogs.TaskLog(ctx, task.ID, task.Attempt, logging.Query{})
if err != nil {
+56 -33
View File
@@ -11,6 +11,7 @@ import (
"github.com/samcharles93/archie-core/internal/domain/binding"
"github.com/samcharles93/archie-core/internal/domain/mapping"
"github.com/samcharles93/archie-core/internal/domain/workflow"
"github.com/samcharles93/archie-core/internal/infrastructure/edastore"
"github.com/samcharles93/archie-core/internal/store"
)
@@ -35,7 +36,7 @@ func TestDispatchBindingsCreatesTaskFromArmedCapture(t *testing.T) {
}
got := tasks[0]
if got.BindingID != bindingID {
t.Errorf("task.BindingID = %d, want %d", got.BindingID, bindingID)
t.Errorf("task.BindingID = %q, want %q", got.BindingID, bindingID)
}
if got.BindingVersion != bindingVersion {
t.Errorf("task.BindingVersion = %d, want %d", got.BindingVersion, bindingVersion)
@@ -170,7 +171,7 @@ func TestDispatchBindingsSkipsWhenResolveFails(t *testing.T) {
if len(tasks) != 0 {
t.Fatalf("required-field failure spawned %d task(s), want 0", len(tasks))
}
events, err := s.EventsSince(t.Context(), 0, 100)
events, err := s.EventsSince(t.Context(), "", 100)
if err != nil {
t.Fatalf("EventsSince: %v", err)
}
@@ -230,9 +231,9 @@ func TestDispatchBindingsNilDispatcherIsNoOp(t *testing.T) {
d := &Daemon{
Cfg: config.NewHolder(config.Config{Repos: []config.Repo{{Owner: "acme", Name: "widget"}}}),
Store: s,
Mappings: s,
Bindings: s,
Store: s.Store,
Mappings: s.EdaStore,
Bindings: s.EdaStore,
// BindingDispatcher and BindingTaskCreator intentionally nil.
Log: slog.New(slog.NewTextHandler(os.Stderr, nil)),
}
@@ -248,22 +249,31 @@ func TestDispatchBindingsNilDispatcherIsNoOp(t *testing.T) {
// production uses (CREATE TABLE + ALTER TABLE migrations), so
// binding_id / binding_version / binding_dispatches all exist on the
// store by the time a test runs.
func openDispatchTestStore(t *testing.T) *store.Store {
// dispatchStores pairs the two stores the dispatcher spans: tasks stay on
// SQLite, event capture is the PocketBase store. They are embedded so a seed
// helper still reads as one handle; the method sets no longer overlap, which
// is exactly what the split bought.
type dispatchStores struct {
*store.Store
EdaStore *edastore.Store
}
func openDispatchTestStore(t *testing.T) *dispatchStores {
t.Helper()
s, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "dispatch.db"))
if err != nil {
t.Fatalf("store.Open: %v", err)
}
t.Cleanup(func() { _ = s.Close() })
return s
return &dispatchStores{Store: s, EdaStore: edastore.OpenTest(t)}
}
// seedMapping inserts a mapping with the given fields and returns its id.
// The Name field is "sentry-mapping" by default; callers pass fields
// inline.
func seedMapping(t *testing.T, s *store.Store, sourceHint string, fields ...mapping.Field) int64 {
func seedMapping(t *testing.T, s *dispatchStores, sourceHint string, fields ...mapping.Field) string {
t.Helper()
id, err := s.InsertMapping(t.Context(), mapping.Mapping{
id, err := s.EdaStore.InsertMapping(t.Context(), mapping.Mapping{
Name: sourceHint + "-mapping",
SourceHint: sourceHint,
Fields: fields,
@@ -281,7 +291,7 @@ func seedMapping(t *testing.T, s *store.Store, sourceHint string, fields ...mapp
// advances through pending_approval via the store's test-only DB
// accessor -- production callers must use the structured methods
// (bindings.go) rather than touching the SQL directly.
func seedArmedBinding(t *testing.T, s *store.Store, source string, mappingID int64) (int64, int) {
func seedArmedBinding(t *testing.T, s *dispatchStores, source, mappingID string) (string, int) {
t.Helper()
return seedArmedBindingWithRepo(t, s, source, mappingID, "", "")
}
@@ -289,9 +299,9 @@ func seedArmedBinding(t *testing.T, s *store.Store, source string, mappingID int
// seedArmedBindingWithRepo is seedArmedBinding with an explicit
// owner/repo pin (pass "", "" for the unpinned case seedArmedBinding
// covers).
func seedArmedBindingWithRepo(t *testing.T, s *store.Store, source string, mappingID int64, owner, repo string) (int64, int) {
func seedArmedBindingWithRepo(t *testing.T, s *dispatchStores, source, mappingID, owner, repo string) (string, int) {
t.Helper()
id, err := s.InsertBinding(t.Context(), binding.Binding{
id, err := s.EdaStore.InsertBinding(t.Context(), binding.Binding{
Name: "test " + source,
Matcher: binding.Matcher{Source: source},
MappingID: mappingID,
@@ -303,13 +313,25 @@ func seedArmedBindingWithRepo(t *testing.T, s *store.Store, source string, mappi
if err != nil {
t.Fatalf("InsertBinding: %v", err)
}
if _, err := s.DB().ExecContext(t.Context(), `UPDATE bindings SET status='pending_approval' WHERE id=?`, id); err != nil {
t.Fatalf("force pending_approval: %v", err)
// Edit moves a draft to pending_approval through the real lifecycle,
// which is what makes it approvable. The old raw-SQL shortcut reached
// into a table the task store no longer owns.
if err := s.EdaStore.UpdateBinding(t.Context(), binding.Binding{
ID: id,
Name: "test " + source,
Matcher: binding.Matcher{Source: source},
MappingID: mappingID,
Workflow: "implement",
Owner: owner,
Repo: repo,
Secret: "0123456789abcdef0123456789abcdef",
}); err != nil {
t.Fatalf("UpdateBinding to pending_approval: %v", err)
}
if err := s.ApproveBinding(t.Context(), id); err != nil {
if err := s.EdaStore.ApproveBinding(t.Context(), id); err != nil {
t.Fatalf("ApproveBinding: %v", err)
}
got, err := s.GetBinding(t.Context(), id)
got, err := s.EdaStore.GetBinding(t.Context(), id)
if err != nil || got == nil {
t.Fatalf("GetBinding after approve: %+v, %v", got, err)
}
@@ -321,9 +343,9 @@ func seedArmedBindingWithRepo(t *testing.T, s *store.Store, source string, mappi
// the per-insert pruning the production path uses, so a test that
// only needs a single row in the table is not at the mercy of
// maxEvents=0's "no cap" reading.
func seedCapture(t *testing.T, s *store.Store, source string, authenticated bool, body string) {
func seedCapture(t *testing.T, s *dispatchStores, source string, authenticated bool, body string) {
t.Helper()
_, err := s.InsertCapture(t.Context(), store.CapturedEvent{
_, err := s.EdaStore.InsertCapture(t.Context(), store.CapturedEvent{
Source: source,
Body: body,
Authenticated: authenticated,
@@ -341,7 +363,7 @@ func seedCapture(t *testing.T, s *store.Store, source string, authenticated bool
// single-repo fallback accepts the dispatch; with zero or many
// configured repos the loop would log and skip, masking the test's
// positive assertions.
func newDispatchDaemon(t *testing.T, s *store.Store) *Daemon {
func newDispatchDaemon(t *testing.T, s *dispatchStores) *Daemon {
t.Helper()
return newDispatchDaemonWithRepos(t, s, []config.Repo{{Owner: "acme", Name: "widget"}})
}
@@ -349,36 +371,37 @@ func newDispatchDaemon(t *testing.T, s *store.Store) *Daemon {
// newDispatchDaemonWithRepos is newDispatchDaemon with an explicit repo
// list, for tests exercising resolveBindingRepo's owner/repo-pin path
// against zero, one, or several configured repos.
func newDispatchDaemonWithRepos(t *testing.T, s *store.Store, repos []config.Repo) *Daemon {
func newDispatchDaemonWithRepos(t *testing.T, s *dispatchStores, repos []config.Repo) *Daemon {
t.Helper()
cfg := config.Config{Repos: repos}
return &Daemon{
Cfg: config.NewHolder(cfg),
Store: s,
Mappings: s,
Bindings: s,
BindingDispatcher: s,
BindingTaskCreator: s,
Store: s.Store,
Mappings: s.EdaStore,
Bindings: s.EdaStore,
BindingDispatcher: s.EdaStore,
BindingTaskCreator: s.Store,
Log: slog.New(slog.NewTextHandler(os.Stderr, nil)),
}
}
// assertDispatchRecorded reads the dedup ledger directly: the
// (binding_id, capture_id) primary key is what guarantees no double
// (binding, capture) unique index is what guarantees no double
// dispatch. Going through the SQL table rather than the public
// BindingStore surface keeps the assertion focused on the contract
// Phase E actually writes to, not on a ListDispatches helper that
// may not exist.
func assertDispatchRecorded(t *testing.T, s *store.Store, bindingID, taskID int64) {
func assertDispatchRecorded(t *testing.T, s *dispatchStores, bindingID string, taskID int64) {
t.Helper()
var gotBindingID, gotTaskID int64
if err := s.DB().QueryRowContext(
t.Context(),
`SELECT binding_id, task_id FROM binding_dispatches WHERE binding_id=?`, bindingID,
).Scan(&gotBindingID, &gotTaskID); err != nil {
var gotBindingID string
var gotTaskID int64
if err := s.EdaStore.App().DB().NewQuery(
"SELECT binding, task_id FROM binding_dispatches WHERE binding = {:binding}").
Bind(map[string]any{"binding": bindingID}).
Row(&gotBindingID, &gotTaskID); err != nil {
t.Fatalf("binding_dispatches row missing: %v", err)
}
if gotBindingID != bindingID || gotTaskID != taskID {
t.Fatalf("binding_dispatches row = (%d, %d), want (%d, %d)", gotBindingID, gotTaskID, bindingID, taskID)
t.Fatalf("binding_dispatches row = (%q, %d), want (%q, %d)", gotBindingID, gotTaskID, bindingID, taskID)
}
}
+163
View File
@@ -0,0 +1,163 @@
package daemon
import (
"context"
"log/slog"
"strings"
"testing"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/identity"
"github.com/samcharles93/archie-core/internal/domain/workflow"
"github.com/samcharles93/archie-core/internal/domain/workintake"
"github.com/samcharles93/archie-core/internal/eventbus"
"github.com/samcharles93/archie-core/internal/store"
"github.com/samcharles93/archie-core/internal/worktree"
)
// fakeMessage is a minimal eventbus.Message for driving processNATSTask
// without standing up a broker.
type fakeMessage struct {
data []byte
subject string
acked bool
naked bool
}
func (m *fakeMessage) Data() []byte { return m.data }
func (m *fakeMessage) Subject() string { return m.subject }
func (m *fakeMessage) Ack() error { m.acked = true; return nil }
func (m *fakeMessage) Nak() error { m.naked = true; return nil }
var _ eventbus.Message = (*fakeMessage)(nil)
// TestProcessNATSTaskRejectsUnresolvableIdentity pins the intake half of the
// fail-closed relation: a task envelope naming an identity this daemon does
// not know must not be written to the store at all. Today it is enqueued and
// only fails open later, when forgeFor/repoFor fall back to the root forge.
func TestProcessNATSTaskRejectsUnresolvableIdentity(t *testing.T) {
s := store.OpenTest(t)
d := &Daemon{
Store: s,
Cfg: config.NewHolder(config.Config{}),
Trees: &worktree.Manager{},
Log: slog.New(slog.DiscardHandler),
}
data, err := workintake.TaskEnvelope{
Owner: "acme", Repo: "widget", Number: 1, Title: "ghost task",
Identity: "ghost",
}.Encode()
if err != nil {
t.Fatal(err)
}
msg := &fakeMessage{data: data, subject: workintake.SubjectTaskDefault}
d.processNATSTask(t.Context(), msg)
if msg.naked {
t.Fatal("unresolvable identity intake was nacked; a redelivery can never resolve it")
}
if !msg.acked {
t.Fatal("unresolvable identity intake was not dropped (acked)")
}
task, err := s.TaskByIssue(t.Context(), "acme", "widget", 1)
if err != nil {
t.Fatal(err)
}
if task != nil {
t.Fatalf("task %d was created with an unresolvable identity %q", task.ID, task.Identity)
}
}
// TestProcessParksTaskWhoseIdentityNoLongerResolves pins the dispatch half of
// the fail-closed relation: a task whose non-empty identity no longer has a
// configured runner must park, never fall back to the root forge's credential.
func TestProcessParksTaskWhoseIdentityNoLongerResolves(t *testing.T) {
d, s, rootFg, _, _ := twoIdentityDaemon(t)
d.Log = slog.New(slog.DiscardHandler)
ctx := context.Background()
if _, err := s.EnqueueIssue(ctx, "acme", "shared", 42, "t", "b", "", "ghost"); err != nil {
t.Fatal(err)
}
task, err := s.ClaimNext(ctx)
if err != nil || task == nil {
t.Fatalf("ClaimNext = (%+v, %v)", task, err)
}
d.process(ctx, task)
got, err := s.TaskByID(ctx, task.ID)
if err != nil || got == nil {
t.Fatalf("TaskByID = (%+v, %v)", got, err)
}
if got.Status != workflow.StatusParked {
t.Fatalf("status = %q, want parked", got.Status)
}
if !strings.Contains(got.ParkReason, "no longer resolves") {
t.Errorf("ParkReason = %q, want it to name the unresolvable identity", got.ParkReason)
}
// The root forge must not have been touched for this task: parking on an
// identity that no longer resolves is the fail-closed outcome, not a
// fallback to root credentials.
if calls := len(rootFg.stateLabels) + len(rootFg.closedIssues) + len(rootFg.comments); calls != 0 {
t.Errorf("root forge was called %d time(s) for a task with an unresolvable identity", calls)
}
}
// TestProcessParksRetiredIdentity pins the lifecycle half: an identity that
// still has a runner but has been retired may not act, so its tasks park
// rather than running under a credential the control plane has retired.
func TestProcessParksRetiredIdentity(t *testing.T) {
s := store.OpenTest(t)
ctx := context.Background()
log := slog.New(slog.DiscardHandler)
id := identity.StableID("worker")
created, err := identity.New(id, identity.KindBot, "worker")
if err != nil {
t.Fatal(err)
}
created, err = s.Create(ctx, created, identity.Audit{ActorID: identity.SystemID, Source: "test", RequestID: "create"})
if err != nil {
t.Fatal(err)
}
if _, err := s.Apply(ctx, created.ID, created.Version, identity.Command{Type: identity.CommandRetire}, identity.Audit{ActorID: identity.SystemID, Source: "test", RequestID: "retire"}); err != nil {
t.Fatal(err)
}
repo := config.Repo{Owner: "acme", Name: "widget"}
d := &Daemon{
Cfg: config.NewHolder(config.Config{Repos: []config.Repo{repo}}),
Store: s,
Log: log,
IdentityRepository: s,
Identities: []*IdentityRunner{{
Name: "worker", ID: id,
Forge: &testForge{}, Trees: &worktree.Manager{},
Repos: []config.Repo{repo}, Cfg: config.IdentityConfig{Name: "worker"}, Log: log,
}},
}
if _, err := s.EnqueueIssue(ctx, "acme", "widget", 7, "t", "b", "", string(id)); err != nil {
t.Fatal(err)
}
task, err := s.ClaimNext(ctx)
if err != nil || task == nil {
t.Fatalf("ClaimNext = (%+v, %v)", task, err)
}
d.process(ctx, task)
got, err := s.TaskByID(ctx, task.ID)
if err != nil || got == nil {
t.Fatalf("TaskByID = (%+v, %v)", got, err)
}
if got.Status != workflow.StatusParked {
t.Fatalf("status = %q, want parked", got.Status)
}
if !strings.Contains(got.ParkReason, "may not act") {
t.Errorf("ParkReason = %q, want it to name the retired identity", got.ParkReason)
}
}
+234
View File
@@ -0,0 +1,234 @@
package daemon
import (
"context"
"errors"
"fmt"
"log/slog"
"github.com/samcharles93/archie-core/internal/domain/storecontract"
"github.com/samcharles93/archie-core/internal/domain/workflow"
workflowtask "github.com/samcharles93/archie-core/internal/domain/workflow/task"
"github.com/samcharles93/archie-core/internal/domain/workintake"
"github.com/samcharles93/archie-core/internal/eventbus"
)
// ReactionSource is the pull surface the reaction consumer needs: fetch one
// message from the reaction stream, or eventbus.ErrNoMessage when it is
// drained. Narrow on purpose -- the consumer never publishes and never
// subscribes.
type ReactionSource interface {
Fetch(ctx context.Context) (eventbus.Message, error)
}
// maxReactionsPerCycle bounds one drain pass. Reactions are row updates, not
// agent runs, but an unbounded drain could hold the dispatch loop hostage
// behind a burst; anything past the bound waits for the next cycle.
const maxReactionsPerCycle = 32
// remediableReviewStates are the review states a remediation unit addresses.
// approved is a decision-5 exclusion (recording, not remediating; merging
// stays an operator action) and dismissed is withdrawn feedback.
var remediableReviewStates = map[string]bool{
"requested_changes": true,
"commented": true,
}
// reactionConsumer turns forge review reactions on Archie-owned PRs into
// queued remediate runs. It implements the consumer half of
// docs/prds/pr-review-remediation.md decisions 3 and 5: resolve the PR to
// the task that owns it (the authorization boundary), never react to
// Archie's own comments, collect a review's comments into one unit while it
// is pending, and rely on the guarded store transition for dedup.
type reactionConsumer struct {
lookup workintake.ReviewTaskLookup
remediations storecontract.RemediationStarter
botUser func(*workflowtask.Task) string
log *slog.Logger
dropped int64
}
func newReactionConsumer(
lookup workintake.ReviewTaskLookup,
remediations storecontract.RemediationStarter,
botUser func(*workflowtask.Task) string,
log *slog.Logger,
) *reactionConsumer {
return &reactionConsumer{lookup: lookup, remediations: remediations, botUser: botUser, log: log}
}
// drain fetches and handles reactions until the stream is idle or the
// per-cycle bound is reached, returning how many messages it handled.
func (c *reactionConsumer) drain(ctx context.Context, src ReactionSource, limit int) (int, error) {
handled := 0
for handled < limit {
msg, err := src.Fetch(ctx)
if err != nil {
if errors.Is(err, eventbus.ErrNoMessage) {
return handled, nil
}
return handled, fmt.Errorf("fetch reaction: %w", err)
}
if ctx.Err() != nil {
return handled, ctx.Err()
}
c.handle(ctx, msg)
handled++
}
return handled, nil
}
// handle processes one reaction to a terminal outcome: Ack on every decided
// path (drop, dedup, or work queued), Nak only on a transient store failure
// the next delivery can succeed against.
func (c *reactionConsumer) handle(ctx context.Context, msg eventbus.Message) {
envelope, err := workintake.DecodeReviewComment(msg.Data())
if err != nil {
c.log.Error("review reaction decode failed", "subject", msg.Subject(), "err", err)
_ = msg.Ack() // it will never decode on redelivery
return
}
task, err := c.lookup.OpenTaskByPR(ctx, envelope.Owner, envelope.Repo, envelope.PRNumber)
if err != nil {
c.log.Error("review reaction lookup failed", "owner", envelope.Owner, "repo", envelope.Repo, "pr", envelope.PRNumber, "err", err)
_ = msg.Nak()
return
}
if task == nil {
// The resolver counts this: a reaction that does not resolve to a
// live task Archie owns is dropped, never work.
c.drop(msg, "no live task owns this PR")
return
}
if c.botUser(task) != "" && envelope.Author == c.botUser(task) {
// Decision 5: only Archie's own comments are excluded, so its
// ReplyToReview replies never retrigger it. Every other author --
// human or bot -- is actionable.
c.drop(msg, "reaction is archie's own comment")
return
}
switch envelope.Kind {
case workintake.ReviewReactionReview:
c.handleReview(ctx, msg, task, envelope)
case workintake.ReviewReactionComment:
c.handleComment(ctx, msg, task, envelope)
default:
c.drop(msg, "unknown reaction kind")
}
}
func (c *reactionConsumer) handleReview(ctx context.Context, msg eventbus.Message, task *workflowtask.Task, e workintake.ReviewCommentEnvelope) {
if !remediableReviewStates[e.State] {
// approved: no remediation, and never auto-merge (decision 5). The
// review state is visible on the forge itself.
c.drop(msg, fmt.Sprintf("review state %q does not trigger remediation", e.State))
return
}
unit := workflow.ReviewUnit{ReviewID: e.ReviewID, Author: e.Author, State: e.State, Body: e.Body}
payload, err := workflow.EncodeReviewUnit(unit)
if err != nil {
c.log.Error("review unit encode failed", "task", task.ID, "err", err)
_ = msg.Nak()
return
}
if err := c.remediations.BeginRemediation(ctx, task.ID, payload); err != nil {
if errors.Is(err, storecontract.ErrStaleTransition) {
// Already queued or claimed: a re-delivered review, or a second
// reaction for a review whose unit is pending. The guarded
// transition is the dedup.
c.log.Debug("remediation already pending", "task", task.ID, "review", e.ReviewID)
_ = msg.Ack()
return
}
c.log.Error("BeginRemediation failed", "task", task.ID, "err", err)
_ = msg.Nak()
return
}
c.log.Info("review reaction queued a remediation", "task", task.ID, "pr", fmt.Sprintf("%s/%s#%d", e.Owner, e.Repo, e.PRNumber), "review", e.ReviewID, "state", e.State)
_ = msg.Ack()
}
func (c *reactionConsumer) handleComment(ctx context.Context, msg eventbus.Message, task *workflowtask.Task, e workintake.ReviewCommentEnvelope) {
if e.ReviewID == 0 {
// Decision 5: a standalone comment with no parent review is its own
// unit of one.
unit := workflow.ReviewUnit{Comments: []workflow.ReviewUnitComment{{
CommentID: e.CommentID, Path: e.Path, Line: e.Line, Body: e.Body,
}}}
payload, err := workflow.EncodeReviewUnit(unit)
if err != nil {
c.log.Error("review unit encode failed", "task", task.ID, "err", err)
_ = msg.Nak()
return
}
if err := c.remediations.BeginRemediation(ctx, task.ID, payload); err != nil {
if errors.Is(err, storecontract.ErrStaleTransition) {
_ = msg.Ack()
return
}
c.log.Error("BeginRemediation failed", "task", task.ID, "err", err)
_ = msg.Nak()
return
}
_ = msg.Ack()
return
}
// A comment with a parent review is collected into that review's pending
// unit, never dispatched alone. Once the unit has been claimed, its input
// is frozen: a late comment is dropped, and the round cap bounds the
// exchange if the reviewer re-reviews.
if task.Status != workflow.StatusQueued || task.Workflow != "remediate" {
c.drop(msg, "parent review's unit is no longer pending")
return
}
unit, err := workflow.DecodeReviewUnit(task.ReviewPayload)
if err != nil {
if errors.Is(err, workflow.ErrNoReviewPayload) {
c.drop(msg, "queued remediation carries no review unit")
return
}
c.log.Error("review payload decode failed", "task", task.ID, "err", err)
_ = msg.Nak()
return
}
if unit.ReviewID != e.ReviewID {
c.drop(msg, "comment's parent review is not the pending unit")
return
}
for _, existing := range unit.Comments {
if existing.CommentID == e.CommentID {
_ = msg.Ack() // re-delivery of an already-collected comment
return
}
}
unit.Comments = append(unit.Comments, workflow.ReviewUnitComment{
CommentID: e.CommentID, Path: e.Path, Line: e.Line, Body: e.Body,
})
payload, err := workflow.EncodeReviewUnit(unit)
if err != nil {
c.log.Error("review unit encode failed", "task", task.ID, "err", err)
_ = msg.Nak()
return
}
if err := c.remediations.UpdateReviewPayload(ctx, task.ID, payload); err != nil {
if errors.Is(err, storecontract.ErrStaleTransition) {
// Claimed between the read and the write: the unit is frozen.
_ = msg.Ack()
return
}
c.log.Error("UpdateReviewPayload failed", "task", task.ID, "err", err)
_ = msg.Nak()
return
}
_ = msg.Ack()
}
func (c *reactionConsumer) drop(msg eventbus.Message, reason string) {
c.dropped++
c.log.Info("review reaction dropped", "subject", msg.Subject(), "reason", reason)
_ = msg.Ack()
}
+371
View File
@@ -0,0 +1,371 @@
package daemon
import (
"context"
"errors"
"log/slog"
"sync"
"testing"
"github.com/samcharles93/archie-core/internal/domain/storecontract"
"github.com/samcharles93/archie-core/internal/domain/workflow"
workflowtask "github.com/samcharles93/archie-core/internal/domain/workflow/task"
"github.com/samcharles93/archie-core/internal/domain/workintake"
"github.com/samcharles93/archie-core/internal/eventbus"
)
// ---- fakes ----
type fakeReactionSource struct {
mu sync.Mutex
pending []eventbus.Message
fetchErr error
}
func (f *fakeReactionSource) Fetch(ctx context.Context) (eventbus.Message, error) {
f.mu.Lock()
defer f.mu.Unlock()
if f.fetchErr != nil {
return nil, f.fetchErr
}
if len(f.pending) == 0 {
return nil, eventbus.ErrNoMessage
}
m := f.pending[0]
f.pending = f.pending[1:]
return m, nil
}
type fakeReactionMessage struct {
data []byte
subject string
mu sync.Mutex
acked bool
nakked bool
}
func (m *fakeReactionMessage) Data() []byte { return m.data }
func (m *fakeReactionMessage) Subject() string { return m.subject }
func (m *fakeReactionMessage) Ack() error {
m.mu.Lock()
defer m.mu.Unlock()
m.acked = true
return nil
}
func (m *fakeReactionMessage) Nak() error {
m.mu.Lock()
defer m.mu.Unlock()
m.nakked = true
return nil
}
func (m *fakeReactionMessage) wasAcked() bool {
m.mu.Lock()
defer m.mu.Unlock()
return m.acked
}
func (m *fakeReactionMessage) wasNakked() bool {
m.mu.Lock()
defer m.mu.Unlock()
return m.nakked
}
type fakeRemediations struct {
begun []string // payloads handed to BeginRemediation, in order
updated []string
beginErr error
}
func (f *fakeRemediations) BeginRemediation(ctx context.Context, taskID int64, payload string) error {
if f.beginErr != nil {
return f.beginErr
}
f.begun = append(f.begun, payload)
return nil
}
func (f *fakeRemediations) UpdateReviewPayload(ctx context.Context, taskID int64, payload string) error {
f.updated = append(f.updated, payload)
return nil
}
func (f *fakeRemediations) SetReviewCursors(ctx context.Context, taskID, reviewCursor, commentCursor int64) error {
return nil
}
type fakeReviewLookup struct {
task *workflowtask.Task
err error
// sequence, when set, is consulted before task, so a test can model the
// store's fresh read per message (e.g. a unit that queued between two
// reactions).
sequence func(call int) (*workflowtask.Task, error)
calls int
}
func (f *fakeReviewLookup) OpenTaskByPR(ctx context.Context, owner, repo string, number int) (*workflowtask.Task, error) {
f.calls++
if f.sequence != nil {
return f.sequence(f.calls)
}
return f.task, f.err
}
// ---- helpers ----
func reviewEnvelopeJSON(kind string, reviewID, commentID int64, author, state, body string) []byte {
e := workintake.ReviewCommentEnvelope{
Owner: "acme", Repo: "widgets", PRNumber: 42,
Kind: workintake.ReviewReactionKind(kind),
ReviewID: reviewID, CommentID: commentID,
Author: author, State: state, Body: body,
}
data, err := e.Encode()
if err != nil {
panic(err)
}
return data
}
func ownedTask(status, workflowName, payload string) *workflowtask.Task {
t := &workflowtask.Task{
ID: 7, Owner: "acme", Repo: "widgets", PRNumber: 42,
Status: status, Workflow: workflowName, ReviewPayload: payload,
}
return t
}
func newConsumer(task *workflowtask.Task, remediations *fakeRemediations) *reactionConsumer {
return newReactionConsumer(
&fakeReviewLookup{task: task},
remediations,
func(*workflowtask.Task) string { return "archie-bot" },
slog.New(slog.DiscardHandler),
)
}
// ---- tests ----
func TestReactionConsumerReviewEventStartsARemediation(t *testing.T) {
remediations := &fakeRemediations{}
c := newConsumer(ownedTask(workflowtask.StatusPROpen, "implement", ""), remediations)
msg := &fakeReactionMessage{data: reviewEnvelopeJSON("review", 7, 0, "alice", "requested_changes", "please fix x")}
c.handle(context.Background(), msg)
if len(remediations.begun) != 1 {
t.Fatalf("BeginRemediation calls = %d, want 1", len(remediations.begun))
}
unit, err := workflow.DecodeReviewUnit(remediations.begun[0])
if err != nil {
t.Fatal(err)
}
if unit.ReviewID != 7 || unit.State != "requested_changes" || unit.Body != "please fix x" {
t.Errorf("unit = %+v, want the review's own coordinates", unit)
}
if !msg.wasAcked() {
t.Error("message was not acked")
}
}
func TestReactionConsumerApprovedReviewDoesNotRemediate(t *testing.T) {
remediations := &fakeRemediations{}
c := newConsumer(ownedTask(workflowtask.StatusPROpen, "implement", ""), remediations)
msg := &fakeReactionMessage{data: reviewEnvelopeJSON("review", 7, 0, "alice", "approved", "lgtm")}
c.handle(context.Background(), msg)
if len(remediations.begun) != 0 {
t.Errorf("BeginRemediation called for an approved review")
}
if !msg.wasAcked() {
t.Error("message was not acked")
}
}
func TestReactionConsumerOwnCommentNeverRetriggers(t *testing.T) {
remediations := &fakeRemediations{}
c := newConsumer(ownedTask(workflowtask.StatusPROpen, "implement", ""), remediations)
msg := &fakeReactionMessage{data: reviewEnvelopeJSON("comment", 0, 9, "archie-bot", "", "my own reply")}
c.handle(context.Background(), msg)
if len(remediations.begun) != 0 || len(remediations.updated) != 0 {
t.Errorf("own comment triggered work: begun=%d updated=%d", len(remediations.begun), len(remediations.updated))
}
if !msg.wasAcked() {
t.Error("message was not acked")
}
}
func TestReactionConsumerCommentAppendsToThePendingUnitOfItsReview(t *testing.T) {
remediations := &fakeRemediations{}
pending := ownedTask(workflowtask.StatusQueued, "remediate", `{"review_id":7,"state":"requested_changes"}`)
c := newConsumer(pending, remediations)
msg := &fakeReactionMessage{data: reviewEnvelopeJSON("comment", 7, 9, "alice", "", "fix the loop")}
c.handle(context.Background(), msg)
if len(remediations.updated) != 1 {
t.Fatalf("UpdateReviewPayload calls = %d, want 1", len(remediations.updated))
}
unit, err := workflow.DecodeReviewUnit(remediations.updated[0])
if err != nil {
t.Fatal(err)
}
if unit.ReviewID != 7 || len(unit.Comments) != 1 || unit.Comments[0].CommentID != 9 {
t.Errorf("appended unit = %+v, want comment 9 under review 7", unit)
}
// The parent review's summary survives the append.
if unit.State != "requested_changes" {
t.Errorf("unit state = %q, want the parent review's state preserved", unit.State)
}
if !msg.wasAcked() {
t.Error("message was not acked")
}
}
func TestReactionConsumerDuplicateCommentIsNotAppendedTwice(t *testing.T) {
remediations := &fakeRemediations{}
pending := ownedTask(workflowtask.StatusQueued, "remediate", `{"review_id":7,"comments":[{"comment_id":9,"body":"fix the loop"}]}`)
c := newConsumer(pending, remediations)
msg := &fakeReactionMessage{data: reviewEnvelopeJSON("comment", 7, 9, "alice", "", "fix the loop")}
c.handle(context.Background(), msg)
if len(remediations.updated) != 0 {
t.Errorf("UpdateReviewPayload called for a comment the unit already carries")
}
if !msg.wasAcked() {
t.Error("message was not acked")
}
}
func TestReactionConsumerLateCommentAfterDispatchIsDropped(t *testing.T) {
remediations := &fakeRemediations{}
c := newConsumer(ownedTask(workflowtask.StatusPROpen, "implement", ""), remediations)
// A comment carrying a parent review id, but the task is not a queued
// remediation for it: the unit already dispatched.
msg := &fakeReactionMessage{data: reviewEnvelopeJSON("comment", 7, 9, "alice", "", "late comment")}
c.handle(context.Background(), msg)
if len(remediations.begun) != 0 || len(remediations.updated) != 0 {
t.Errorf("late comment mutated store state: begun=%d updated=%d", len(remediations.begun), len(remediations.updated))
}
if !msg.wasAcked() {
t.Error("message was not acked")
}
}
func TestReactionConsumerStandaloneCommentIsItsOwnUnit(t *testing.T) {
remediations := &fakeRemediations{}
c := newConsumer(ownedTask(workflowtask.StatusPROpen, "implement", ""), remediations)
msg := &fakeReactionMessage{data: reviewEnvelopeJSON("comment", 0, 12, "alice", "", "nit: rename")}
c.handle(context.Background(), msg)
if len(remediations.begun) != 1 {
t.Fatalf("BeginRemediation calls = %d, want 1", len(remediations.begun))
}
unit, err := workflow.DecodeReviewUnit(remediations.begun[0])
if err != nil {
t.Fatal(err)
}
if len(unit.Comments) != 1 || unit.Comments[0].CommentID != 12 {
t.Errorf("unit = %+v, want one standalone comment", unit)
}
if !msg.wasAcked() {
t.Error("message was not acked")
}
}
func TestReactionConsumerUnresolvablePRIsDropped(t *testing.T) {
remediations := &fakeRemediations{}
// nil task: the PR does not belong to an archie-owned task.
c := newConsumer(nil, remediations)
msg := &fakeReactionMessage{data: reviewEnvelopeJSON("review", 7, 0, "alice", "requested_changes", "unrelated")}
c.handle(context.Background(), msg)
if len(remediations.begun) != 0 {
t.Errorf("reaction for a foreign PR started work")
}
if !msg.wasAcked() {
t.Error("message was not acked")
}
}
func TestReactionConsumerInvalidEnvelopeIsAckedNotRedelivered(t *testing.T) {
remediations := &fakeRemediations{}
c := newConsumer(ownedTask(workflowtask.StatusPROpen, "implement", ""), remediations)
msg := &fakeReactionMessage{data: []byte(`{"owner":"acme"}`)} // no kind, no ids
c.handle(context.Background(), msg)
if len(remediations.begun) != 0 {
t.Errorf("invalid envelope started work")
}
if !msg.wasAcked() {
t.Error("message was not acked")
}
}
func TestReactionConsumerTransientStoreErrorNaks(t *testing.T) {
remediations := &fakeRemediations{beginErr: errors.New("db unavailable")}
c := newConsumer(ownedTask(workflowtask.StatusPROpen, "implement", ""), remediations)
msg := &fakeReactionMessage{data: reviewEnvelopeJSON("review", 7, 0, "alice", "requested_changes", "please fix x")}
c.handle(context.Background(), msg)
if !msg.wasNakked() {
t.Error("transient failure was not nakked for redelivery")
}
if msg.wasAcked() {
t.Error("transient failure was acked")
}
}
func TestReactionConsumerDrainsUntilIdle(t *testing.T) {
remediations := &fakeRemediations{}
// The lookup reads the row fresh per message: the review event queues the
// remediation, so the comment event resolves against the queued unit.
lookup := &fakeReviewLookup{sequence: func(call int) (*workflowtask.Task, error) {
if call == 1 {
return ownedTask(workflowtask.StatusPROpen, "implement", ""), nil
}
return ownedTask(workflowtask.StatusQueued, "remediate", `{"review_id":7,"state":"requested_changes","body":"one"}`), nil
}}
c := newReactionConsumer(lookup, remediations, func(*workflowtask.Task) string { return "archie-bot" }, slog.New(slog.DiscardHandler))
src := &fakeReactionSource{pending: []eventbus.Message{
&fakeReactionMessage{data: reviewEnvelopeJSON("review", 7, 0, "alice", "requested_changes", "one")},
&fakeReactionMessage{data: reviewEnvelopeJSON("comment", 7, 8, "alice", "", "one-a")},
}}
n, err := c.drain(context.Background(), src, 8)
if err != nil {
t.Fatal(err)
}
if n != 2 {
t.Errorf("handled = %d, want 2", n)
}
// The review queued the unit; the comment appended to it.
if len(remediations.begun) != 1 || len(remediations.updated) != 1 {
t.Errorf("begun=%d updated=%d, want 1/1", len(remediations.begun), len(remediations.updated))
}
unit, err := workflow.DecodeReviewUnit(remediations.updated[0])
if err != nil {
t.Fatal(err)
}
if len(unit.Comments) != 1 || unit.Comments[0].CommentID != 8 {
t.Errorf("appended unit = %+v, want comment 8 collected under review 7", unit)
}
}
// compile-time interface checks
var (
_ workintake.ReviewTaskLookup = (*fakeReviewLookup)(nil)
_ storecontract.RemediationStarter = (*fakeRemediations)(nil)
)
+141
View File
@@ -0,0 +1,141 @@
package daemon
import (
"context"
"fmt"
workflowtask "github.com/samcharles93/archie-core/internal/domain/workflow/task"
"github.com/samcharles93/archie-core/internal/domain/workintake"
"github.com/samcharles93/archie-core/internal/forge"
)
// ReactionPublisher delivers one reaction to the reaction stream. The
// composition root wires it to the task bus's PublishUnique against the
// reaction subject, so webhook and poll deliveries of the same record dedup
// on the envelope's source-independent key.
type ReactionPublisher func(ctx context.Context, reaction workintake.ReviewCommentEnvelope) error
// scanPRReviewReactions is the poll backstop's core for one PR (decision 2):
// list review activity since the task's persisted cursors, publish every
// non-own record as a reaction, and return the advanced cursors. The cursors
// advance past every record seen -- skipped own comments included -- so a
// record is listed once and never re-listed on a later scan. On a publish
// failure the error carries: the caller keeps the old cursors, and the next
// scan re-fetches the records it did not get to (PublishUnique's dedup
// absorbs any re-delivery).
func scanPRReviewReactions(
ctx context.Context,
reader forge.PullRequestReviewReader,
task *workflowtask.Task,
botUser string,
reviewCursor, commentCursor int64,
publish ReactionPublisher,
) (int64, int64, error) {
newReviewCursor, newCommentCursor := reviewCursor, commentCursor
reviews, err := reader.ListReviews(ctx, task.Owner, task.Repo, task.PRNumber, reviewCursor)
if err != nil {
return reviewCursor, commentCursor, err
}
for _, r := range reviews {
if r.ID > newReviewCursor {
newReviewCursor = r.ID
}
if botUser != "" && r.Author == botUser {
continue
}
reaction := workintake.ReviewCommentEnvelope{
Owner: task.Owner, Repo: task.Repo, PRNumber: task.PRNumber,
Kind: workintake.ReviewReactionReview,
ReviewID: r.ID, Author: r.Author, State: r.State, Body: r.Body,
}
if err := publish(ctx, reaction); err != nil {
return reviewCursor, commentCursor, fmt.Errorf("publish review %d: %w", r.ID, err)
}
}
comments, err := reader.ListReviewComments(ctx, task.Owner, task.Repo, task.PRNumber, commentCursor)
if err != nil {
return reviewCursor, commentCursor, err
}
for _, cm := range comments {
if cm.ID > newCommentCursor {
newCommentCursor = cm.ID
}
if botUser != "" && cm.Author == botUser {
continue
}
reaction := workintake.ReviewCommentEnvelope{
Owner: task.Owner, Repo: task.Repo, PRNumber: task.PRNumber,
Kind: workintake.ReviewReactionComment,
ReviewID: cm.ReviewID,
CommentID: cm.ID,
Author: cm.Author, Body: cm.Body, Path: cm.Path, Line: cm.Line,
}
if err := publish(ctx, reaction); err != nil {
return reviewCursor, commentCursor, fmt.Errorf("publish comment %d: %w", cm.ID, err)
}
}
return newReviewCursor, newCommentCursor, nil
}
// scanPRReviews runs the shared per-PR review scan over every open PR task
// (reconcilePRs's shape): one pass over all pr_open tasks, each scanned with
// the forge client its own identity owns. A forge without the review-reader
// capability is skipped, not an error. Wired after reconcilePRs so a PR
// that just left pr_open is not scanned for reactions in the same pass.
func (d *Daemon) scanPRReviews(ctx context.Context) {
if d.Store == nil || d.Tasks == nil {
return
}
tasks, err := d.Store.OpenPRs(ctx)
if err != nil {
d.Log.Error("review scan query failed", "err", err)
return
}
if d.reactionPublisher == nil {
d.reactionPublisher = d.publishReaction
}
for i := range tasks {
t := &tasks[i]
reader, ok := d.forgeFor(t).(forge.PullRequestReviewReader)
if !ok {
continue // the noop forge and any forge without the capability
}
d.scanOnePR(ctx, reader, t)
}
}
func (d *Daemon) scanOnePR(ctx context.Context, reader forge.PullRequestReviewReader, t *workflowtask.Task) {
// A forge read failure skips the task for this scan with its cursors
// unchanged: the next scan re-fetches, and PublishUnique's dedup covers
// anything the previous scan already published.
reviewCursor, commentCursor, err := scanPRReviewReactions(
ctx, reader, t, d.botUserForTask(t),
t.ReviewCursor, t.WatchCommentID, d.reactionPublisher)
if err != nil {
d.Log.Warn("review scan failed", "repo", t.Owner+"/"+t.Repo, "pr", t.PRNumber, "err", err)
return
}
if reviewCursor == t.ReviewCursor && commentCursor == t.WatchCommentID {
return
}
if err := d.Store.SetReviewCursors(ctx, t.ID, reviewCursor, commentCursor); err != nil {
// A stale guard here means the task was claimed between the scan and
// the write; the next scan re-reads and re-lists from the old cursor,
// and PublishUnique plus the consumer's dedup absorb the repeats.
d.Log.Warn("review cursor persist failed", "task", t.ID, "err", err)
}
}
// publishReaction encodes one reaction and publishes it on the reaction
// subject with its source-independent idempotency key, so a webhook delivery
// and a poll record of the same review collapse into one.
func (d *Daemon) publishReaction(ctx context.Context, reaction workintake.ReviewCommentEnvelope) error {
payload, err := reaction.Encode()
if err != nil {
return err
}
return d.Tasks.PublishUnique(ctx, reaction.Subject(), reaction.IdempotencyKey(), payload)
}
+138
View File
@@ -0,0 +1,138 @@
package daemon
import (
"context"
"errors"
"testing"
workflowtask "github.com/samcharles93/archie-core/internal/domain/workflow/task"
"github.com/samcharles93/archie-core/internal/domain/workintake"
"github.com/samcharles93/archie-core/internal/forge"
)
type fakeReviewReader struct {
reviews []forge.Review
comments []forge.ReviewComment
listErr error
}
func (f *fakeReviewReader) ListReviews(ctx context.Context, owner, repo string, number int, sinceID int64) ([]forge.Review, error) {
// The real implementations filter on the forge; the fake models the
// contract so "records at or below the cursor never come back" is
// actually exercised.
var out []forge.Review
for _, r := range f.reviews {
if r.ID > sinceID {
out = append(out, r)
}
}
return out, f.listErr
}
func (f *fakeReviewReader) ListReviewComments(ctx context.Context, owner, repo string, number int, sinceID int64) ([]forge.ReviewComment, error) {
var out []forge.ReviewComment
for _, c := range f.comments {
if c.ID > sinceID {
out = append(out, c)
}
}
return out, f.listErr
}
func (f *fakeReviewReader) ReplyToReview(ctx context.Context, owner, repo string, number int, inReplyTo int64, body string) error {
return nil
}
type recordingPublisher struct {
reactions []workintake.ReviewCommentEnvelope
err error
}
func (p *recordingPublisher) publish(ctx context.Context, e workintake.ReviewCommentEnvelope) error {
if p.err != nil {
return p.err
}
p.reactions = append(p.reactions, e)
return nil
}
func openTask(prNumber int, reviewCursor, commentCursor int64) *workflowtask.Task {
return &workflowtask.Task{ID: 7, Owner: "acme", Repo: "widgets", PRNumber: prNumber, Status: "pr_open", ReviewCursor: reviewCursor, WatchCommentID: commentCursor}
}
func TestScanPRReviewReactionsPublishesNewRecordsAndSkipsOwn(t *testing.T) {
reader := &fakeReviewReader{
reviews: []forge.Review{
{ID: 5, Author: "archie-bot", State: "requested_changes", Body: "mine"},
{ID: 7, Author: "alice", State: "requested_changes", Body: "please fix"},
},
comments: []forge.ReviewComment{
{ID: 9, ReviewID: 7, Author: "archie-bot", Body: "my reply"},
{ID: 11, ReviewID: 7, Author: "bob", Body: "also this", Path: "x.go", Line: 3},
},
}
publisher := &recordingPublisher{}
task := openTask(42, 0, 0)
reviewCursor, commentCursor, err := scanPRReviewReactions(
context.Background(), reader, task, "archie-bot", 0, 0, publisher.publish)
if err != nil {
t.Fatal(err)
}
// The own review and own reply are excluded; alice's review and bob's
// comment are the two actionable records.
if len(publisher.reactions) != 2 {
t.Fatalf("published = %d, want 2", len(publisher.reactions))
}
if publisher.reactions[0].Kind != workintake.ReviewReactionReview || publisher.reactions[0].ReviewID != 7 {
t.Errorf("first reaction = %+v, want alice's review 7", publisher.reactions[0])
}
if publisher.reactions[1].Kind != workintake.ReviewReactionComment || publisher.reactions[1].CommentID != 11 {
t.Errorf("second reaction = %+v, want bob's comment 11", publisher.reactions[1])
}
if publisher.reactions[1].ReviewID != 7 {
t.Errorf("comment reaction ReviewID = %d, want 7 (collected under its review)", publisher.reactions[1].ReviewID)
}
if publisher.reactions[1].Body != "also this" || publisher.reactions[1].Path != "x.go" || publisher.reactions[1].Line != 3 {
t.Errorf("comment payload = %+v, want the comment's own content", publisher.reactions[1])
}
// Cursors advance past every record seen, own or not: a cursor that
// stalls on a skipped record would re-list it every scan forever.
if reviewCursor != 7 || commentCursor != 11 {
t.Errorf("cursors = (%d, %d), want (7, 11)", reviewCursor, commentCursor)
}
}
func TestScanPRReviewReactionsSkipRecordsAtOrBelowTheCursors(t *testing.T) {
reader := &fakeReviewReader{
reviews: []forge.Review{{ID: 5, Author: "alice", State: "requested_changes", Body: "old"}},
comments: []forge.ReviewComment{{ID: 6, ReviewID: 5, Author: "bob", Body: "old comment"}},
}
publisher := &recordingPublisher{}
reviewCursor, commentCursor, err := scanPRReviewReactions(
context.Background(), reader, openTask(42, 5, 6), "archie-bot", 5, 6, publisher.publish)
if err != nil {
t.Fatal(err)
}
if len(publisher.reactions) != 0 {
t.Errorf("published %d reactions for records at or below the cursors", len(publisher.reactions))
}
if reviewCursor != 5 || commentCursor != 6 {
t.Errorf("cursors = (%d, %d), want unchanged (5, 6)", reviewCursor, commentCursor)
}
}
func TestScanPRReviewReactionsKeepsCursorsOnPublishFailure(t *testing.T) {
reader := &fakeReviewReader{
reviews: []forge.Review{{ID: 7, Author: "alice", State: "requested_changes", Body: "fix"}},
}
publisher := &recordingPublisher{err: errors.New("bus unavailable")}
_, _, err := scanPRReviewReactions(
context.Background(), reader, openTask(42, 0, 0), "archie-bot", 0, 0, publisher.publish)
if err == nil {
t.Fatal("publish error was swallowed; the cursors must not advance past unpublished records")
}
}
+2 -1
View File
@@ -25,6 +25,7 @@ import (
"github.com/samcharles93/archie-core/internal/storage"
"github.com/samcharles93/archie-core/internal/store"
"github.com/samcharles93/archie-core/internal/taskrun"
"github.com/samcharles93/archie-core/internal/taskstate"
"github.com/samcharles93/archie-core/internal/worktree"
)
@@ -445,7 +446,7 @@ func TestParkRunningTaskGuardedAndLogging(t *testing.T) {
_ = s.Close()
}
d.parkRunningTask(callCtx, task.ID, "simulated park reason")
d.parkRunningTask(callCtx, task.ID, "simulated park reason", taskstate.ParkTransient)
logOutput := buf.String()
if tt.wantWarning {
+4 -4
View File
@@ -43,10 +43,10 @@ type Matcher struct {
// for an event to be marked authenticated; it is never returned by
// GET handlers.
type Binding struct {
ID int64 `json:"id"`
ID string `json:"id"`
Name string `json:"name"`
Matcher Matcher `json:"matcher"`
MappingID int64 `json:"mapping_id"`
MappingID string `json:"mapping_id"`
Workflow string `json:"workflow"`
// Owner and Repo pin a binding to a specific configured repo, so a
// multi-repo deployment can dispatch correctly. Both empty means "no
@@ -110,8 +110,8 @@ func (b Binding) validateCommon() error {
if strings.TrimSpace(b.Matcher.Source) == "" {
return fmt.Errorf("binding: matcher.source is required")
}
if b.MappingID <= 0 {
return fmt.Errorf("binding: mapping_id must be positive")
if strings.TrimSpace(b.MappingID) == "" {
return fmt.Errorf("binding: mapping_id is required")
}
if strings.TrimSpace(b.Workflow) == "" {
return fmt.Errorf("binding: workflow is required")
+1 -1
View File
@@ -6,7 +6,7 @@ func validBinding() Binding {
return Binding{
Name: "sentry alerts",
Matcher: Matcher{Source: "sentry"},
MappingID: 1,
MappingID: "m1",
Workflow: "implement",
Secret: "0123456789abcdef0123456789abcdef",
}
+1 -1
View File
@@ -50,7 +50,7 @@ type Field struct {
// through one example captured event but not pinned to that event or its
// source -- t2db.4's matcher decides which events a binding applies to.
type Mapping struct {
ID int64 `json:"id"`
ID string `json:"id"`
Name string `json:"name"`
SourceHint string `json:"source_hint"`
Fields []Field `json:"fields"`
+112
View File
@@ -0,0 +1,112 @@
package scheduling
import (
"errors"
"time"
)
// Kind values for JobSpec.Kind: the discriminator that decides which delivery
// runner handles a job.
//
// They live beside the field that carries them because they are part of the
// schedules vocabulary an operator writes into the schedules document, a strict
// decoder reads back, and a build that never heard of a kind must reject loudly
// rather than deliver the wrong way. Which runner serves a kind is not this
// package's business: the router in internal/infrastructure/crondelivery owns
// that mapping, which is why an unrecognised kind is stored verbatim rather
// than refused at write time.
const (
// KindChat delivers the job's Payload.Text as a chat message through the
// deployment's channel. It is the default: an empty Kind means KindChat,
// so every job written before this field existed keeps delivering the
// way it did when it was created.
KindChat = "chat"
// KindWorkflow submits the job as a unit of work through the work-intake
// path, so the existing task lifecycle owns scheduling, retries, gates
// and PR opening.
KindWorkflow = "workflow"
)
// JobSpec is one scheduled job as the schedules document persists it, plus
// the bookkeeping fields the scheduler computes (NextRun, LastRun, Created,
// Updated). The wire shape is the public API; the scheduling.Job returned
// to the engine is a stripped subset.
type JobSpec struct {
// ID is the unique identifier. Required, non-empty, and the merge
// key for run recording.
ID string `json:"id"`
// Pool is "parallel" or "sequential". Empty means sequential — the
// safer default, matching Pool.resolve().
Pool string `json:"pool,omitempty"`
// Detail is a human-readable label rendered on events.
Detail string `json:"detail,omitempty"`
// Kind selects which delivery runner handles this job. Empty means
// KindChat, so a job written before this field existed keeps
// delivering as a chat message. This package does not interpret the
// value: an unrecognised kind is stored verbatim and refused by the
// delivery router, which is the one place the mapping from kind to
// runner lives.
Kind string `json:"kind,omitempty"`
// Schedule decides when this job is due. See schedule.go for the
// supported kinds and their arithmetic.
Schedule Schedule `json:"schedule"`
// Target and Payload describe where the job's output goes and what it
// carries. They live on the wire so jobs created ahead of the delivery
// runners that read them do not need a shape migration.
Target Target `json:"target"`
Payload Payload `json:"payload"`
// NextRun is the absolute moment the job will next fire. Computed
// at write time so the engine's hot path is a single comparison.
NextRun time.Time `json:"next_run"`
// LastRun is the last run time reported by the run-recording step,
// nil if the job has never run. The schedule does not know whether
// the run succeeded — that judgement belongs to the runner.
LastRun *time.Time `json:"last_run,omitempty"`
// Created and Updated are audit metadata written by the document's
// owner; the engine does not read them.
Created time.Time `json:"created"`
Updated time.Time `json:"updated"`
}
// Target identifies where the job's output goes. Empty Target is valid —
// the delivery runner chooses a default.
type Target struct {
// ChatID is the chat channel id (Telegram chat id, email address,
// webhook URL — depends on the channel). Empty defers to a default
// chosen by the delivery runner.
ChatID string `json:"chat_id,omitempty"`
}
// Payload is the content sent at run time.
type Payload struct {
// Text is the literal message body. Templating is a future concern
// and is deliberately absent here.
Text string `json:"text,omitempty"`
}
// Sentinels the schedule vocabulary and its callers match with errors.Is.
var (
// ErrJobNotFound is returned by a job source when the requested id
// is absent from its document.
ErrJobNotFound = errors.New("scheduling: job not found")
// ErrInvalidSpec is returned when a JobSpec or Schedule fails
// structural validation (empty id, unknown schedule kind,
// non-positive interval).
ErrInvalidSpec = errors.New("scheduling: invalid job spec")
// ErrScheduleUnsupported is returned when a job's schedule kind
// cannot compute its next run time. Interval arithmetic is fully
// implemented; cron and once return this so callers can surface a
// clear error rather than silently advancing.
ErrScheduleUnsupported = errors.New("scheduling: schedule kind not implemented")
)
@@ -1,9 +1,11 @@
package cronstore
package scheduling
import (
"encoding/json"
"fmt"
"time"
"github.com/pocketbase/pocketbase/tools/cron"
)
// Duration is a schedule interval as the document writes it: the human string
@@ -77,21 +79,22 @@ type Schedule struct {
Start time.Time `json:"start"`
}
// Schedule kinds the store recognises. Slice 1 fully implements
// Interval; Once is accepted at Create / fires at Due exactly once, but
// has no next-run arithmetic for MarkRun (one-shot by definition). Cron
// is parsed at Create but has no firing arithmetic yet — Slice 2 will
// add the parser. MarkRun on a kind this build does not implement
// returns ErrScheduleUnsupported rather than silently advancing next_run.
// Schedule kinds the store recognises. Interval and Cron have full
// next-run arithmetic; Once is accepted at Create / fires at Due exactly
// once, but has no next-run arithmetic for MarkRun (one-shot by
// definition). MarkRun on a kind this build does not implement returns
// ErrScheduleUnsupported rather than silently advancing next_run.
const (
// ScheduleInterval fires every Interval after the last successful run
// (or after Start, if never run). The simplest recurring schedule.
ScheduleInterval = "interval"
// ScheduleCron fires at the next moment matching a standard 5-field
// cron expression after the last successful run. Slice 2 will add
// the parser; until then, MarkRun on a cron job returns
// ErrScheduleUnsupported.
// ScheduleCron fires at the next moment matching a 5-field cron
// expression (or one of the @ macros) after the last successful
// run, computed in the zone of that run time. Expressions are parsed
// with pocketbase tools/cron, which ANDs day-of-month with day-of-week
// instead of Vixie cron's OR: "0 0 1 * 1" means only Monday the 1st,
// not "the 1st or any Monday".
ScheduleCron = "cron"
// ScheduleOnce fires once at the configured At time. Subsequent
@@ -110,8 +113,8 @@ func (s Schedule) Validate() error {
return fmt.Errorf("%w: interval must be positive, got %v", ErrInvalidSpec, s.Interval)
}
case ScheduleCron:
if s.Cron == "" {
return fmt.Errorf("%w: cron expression must be non-empty", ErrInvalidSpec)
if _, err := parseCronSpec(s.Cron); err != nil {
return err
}
case ScheduleOnce:
if s.At == nil {
@@ -136,8 +139,8 @@ func (s Schedule) resolve() Schedule {
// firstRun returns when the job should fire the very first time it has
// never run before. For Interval, it is Start + Interval (or now + Interval
// when Start is zero, so a freshly-created job with no Start still has a
// finite next-run). For Once, it is At. For Cron, it is left as a future
// responsibility — Slice 1 will not synthesise a value it cannot honour.
// finite next-run). For Once, it is At. For Cron, it is the first matching
// minute strictly after Start (or after now when Start is zero).
func (s Schedule) firstRun(now time.Time) (time.Time, error) {
switch s.resolve().Kind {
case ScheduleInterval:
@@ -151,12 +154,62 @@ func (s Schedule) firstRun(now time.Time) (time.Time, error) {
}
return *s.At, nil
case ScheduleCron:
return time.Time{}, fmt.Errorf("%w: cron parsing not yet implemented (slice 2)", ErrScheduleUnsupported)
sched, err := parseCronSpec(s.Cron)
if err != nil {
return time.Time{}, err
}
anchor := now
if !s.Start.IsZero() {
anchor = s.Start
}
return nextCronRun(sched, anchor)
default:
return time.Time{}, fmt.Errorf("%w: unknown kind %q", ErrScheduleUnsupported, s.Kind)
}
}
// parseCronSpec parses expr with pocketbase tools/cron — the project's
// chosen cron dialect: standard 5-field expressions plus the @yearly,
// @monthly, @weekly, @daily and @hourly macros — and wraps any parse
// failure in ErrInvalidSpec so callers need only the one sentinel.
func parseCronSpec(expr string) (*cron.Schedule, error) {
sched, err := cron.NewSchedule(expr)
if err != nil {
return nil, fmt.Errorf("%w: cron expression %q: %w", ErrInvalidSpec, expr, err)
}
return sched, nil
}
// cronHorizon bounds the next-run scan. A satisfiable expression always
// fires well within it (the sparsest realistic case, Feb 29, recurs every
// four years); only a spec that can never fire — e.g. "0 0 30 2 *", which
// the parser's field ranges cannot reject — exhausts the scan.
const cronHorizon = 5 * 365 * 24 * time.Hour
// nextCronRun returns the first wall-clock minute in the location of from
// at which sched is due, strictly after the minute containing from — the
// minute that just fired is never its own successor. Whole months and
// hours that cannot match are skipped, so even a sparse expression costs
// a handful of iterations per year scanned.
func nextCronRun(sched *cron.Schedule, from time.Time) (time.Time, error) {
t := from.Truncate(time.Minute).Add(time.Minute)
for limit := from.Add(cronHorizon); t.Before(limit); {
if sched.IsDue(cron.NewMoment(t)) {
return t, nil
}
if _, ok := sched.Months[int(t.Month())]; !ok {
t = time.Date(t.Year(), t.Month(), 1, 0, 0, 0, 0, t.Location()).AddDate(0, 1, 0)
continue
}
if _, ok := sched.Hours[t.Hour()]; !ok {
t = t.Add(time.Hour).Truncate(time.Hour)
continue
}
t = t.Add(time.Minute)
}
return time.Time{}, fmt.Errorf("%w: cron expression does not match any minute within the next five years", ErrInvalidSpec)
}
func (s Schedule) FirstRun(now time.Time) (time.Time, error) { return s.firstRun(now) }
func (s Schedule) NextRun(lastRun time.Time) (time.Time, error) { return s.nextRun(lastRun) }
@@ -165,9 +218,9 @@ func (s Schedule) Resolved() Schedule { return s.resolve() }
// nextRun returns when the job should fire after a successful run at
// lastRun. It is the engine-side counterpart to firstRun: every MarkRun
// advances next_run through this function. Interval is fully implemented;
// Once and Cron deliberately fail so a silently-wrong value cannot reach
// the ticker.
// advances next_run through this function. Interval and Cron are fully
// implemented; Once deliberately fails (there is no recurring next run)
// so a silently-wrong value cannot reach the ticker.
func (s Schedule) nextRun(lastRun time.Time) (time.Time, error) {
switch s.resolve().Kind {
case ScheduleInterval:
@@ -175,7 +228,11 @@ func (s Schedule) nextRun(lastRun time.Time) (time.Time, error) {
case ScheduleOnce:
return time.Time{}, fmt.Errorf("%w: once schedule has no next run", ErrScheduleUnsupported)
case ScheduleCron:
return time.Time{}, fmt.Errorf("%w: cron arithmetic not yet implemented (slice 2)", ErrScheduleUnsupported)
sched, err := parseCronSpec(s.Cron)
if err != nil {
return time.Time{}, err
}
return nextCronRun(sched, lastRun)
default:
return time.Time{}, fmt.Errorf("%w: unknown kind %q", ErrScheduleUnsupported, s.Kind)
}
+237
View File
@@ -0,0 +1,237 @@
package scheduling
import (
"errors"
"testing"
"time"
)
// testZone is a fixed +02:00 zone: explicit, DST-free, and distinct from UTC
// so any arithmetic that silently computes in UTC fails. Every schedule test
// builds its times here, making the suite independent of the host's TZ.
var testZone = time.FixedZone("TEST", 2*60*60)
// zoned builds a wall-clock time in the fixed test zone.
func zoned(year int, month time.Month, day, hour, minute, sec int) time.Time {
return time.Date(year, month, day, hour, minute, sec, 0, testZone)
}
func TestScheduleCronNextRun(t *testing.T) {
tests := []struct {
name string
expr string
lastRun time.Time
want time.Time
}{
{
name: "minute later in the same hour",
expr: "30 14 * * *",
lastRun: zoned(2026, 8, 24, 13, 0, 0),
want: zoned(2026, 8, 24, 14, 30, 0),
},
{
name: "hour boundary skips the remainder of the hour",
expr: "*/15 * * * *",
lastRun: zoned(2026, 8, 24, 12, 7, 0),
want: zoned(2026, 8, 24, 12, 15, 0),
},
{
// pins the pocketbase AND semantics: Vixie cron would give the
// next Monday (2026-08-31); tools/cron gives Monday the 1st.
name: "dual-restricted day-of-month and day-of-week AND, not Vixie OR",
expr: "0 0 1 * 1",
lastRun: zoned(2026, 8, 24, 12, 15, 30),
want: zoned(2027, 2, 1, 0, 0, 0),
},
{
name: "run exactly on a matching minute advances to the next one",
expr: "0 * * * *",
lastRun: zoned(2026, 8, 24, 12, 0, 0),
want: zoned(2026, 8, 24, 13, 0, 0),
},
{
name: "across the hour boundary",
expr: "5,35 * * * *",
lastRun: zoned(2026, 8, 24, 12, 36, 0),
want: zoned(2026, 8, 24, 13, 5, 0),
},
{
name: "range with step across hours",
expr: "0 9-17/2 * * *",
lastRun: zoned(2026, 8, 24, 10, 0, 0),
want: zoned(2026, 8, 24, 11, 0, 0),
},
{
name: "across midnight",
expr: "0 0 * * *",
lastRun: zoned(2026, 8, 24, 23, 59, 0),
want: zoned(2026, 8, 25, 0, 0, 0),
},
{
name: "across the month boundary",
expr: "0 0 1 * *",
lastRun: zoned(2026, 8, 31, 12, 0, 0),
want: zoned(2026, 9, 1, 0, 0, 0),
},
{
name: "weekday rolls to next Monday",
expr: "0 0 * * 1",
lastRun: zoned(2026, 8, 21, 10, 0, 0),
want: zoned(2026, 8, 24, 0, 0, 0),
},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
s := Schedule{Kind: ScheduleCron, Cron: tc.expr}
got, err := s.NextRun(tc.lastRun)
if err != nil {
t.Fatalf("NextRun(%v): %v", tc.lastRun, err)
}
if !got.Equal(tc.want) {
t.Fatalf("NextRun(%v) = %v (%s), want %v (%s)",
tc.lastRun, got, got.Format("2006-01-02 15:04:05 MST"),
tc.want, tc.want.Format("2006-01-02 15:04:05 MST"))
}
})
}
}
func TestScheduleCronNextRunMacros(t *testing.T) {
// lastRun is Monday 2026-08-24 12:15:30 TEST.
lastRun := zoned(2026, 8, 24, 12, 15, 30)
tests := []struct {
name string
expr string
want time.Time
}{
{name: "@hourly", expr: "@hourly", want: zoned(2026, 8, 24, 13, 0, 0)},
{name: "@daily", expr: "@daily", want: zoned(2026, 8, 25, 0, 0, 0)},
{name: "@midnight", expr: "@midnight", want: zoned(2026, 8, 25, 0, 0, 0)},
{name: "@weekly", expr: "@weekly", want: zoned(2026, 8, 30, 0, 0, 0)},
{name: "@monthly", expr: "@monthly", want: zoned(2026, 9, 1, 0, 0, 0)},
{name: "@yearly", expr: "@yearly", want: zoned(2027, 1, 1, 0, 0, 0)},
{name: "@annually", expr: "@annually", want: zoned(2027, 1, 1, 0, 0, 0)},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
s := Schedule{Kind: ScheduleCron, Cron: tc.expr}
got, err := s.NextRun(lastRun)
if err != nil {
t.Fatalf("NextRun(%v): %v", lastRun, err)
}
if !got.Equal(tc.want) {
t.Fatalf("NextRun(%v) with %q = %v, want %v", lastRun, tc.expr, got, tc.want)
}
})
}
}
func TestScheduleCronComputesInThePassedZone(t *testing.T) {
s := Schedule{Kind: ScheduleCron, Cron: "0 6 * * *"}
// lastRun 05:30 in +02:00: 06:00 local is 04:00 UTC.
got, err := s.NextRun(zoned(2026, 8, 24, 5, 30, 0))
if err != nil {
t.Fatalf("NextRun: %v", err)
}
if want := time.Date(2026, 8, 24, 4, 0, 0, 0, time.UTC); !got.Equal(want) {
t.Fatalf("fixed-zone NextRun = %v (%s), want %v UTC", got, got.Format("15:04 MST"), want)
}
// The same wall-clock spec anchored in UTC must land on 06:00 UTC instead.
got, err = s.NextRun(time.Date(2026, 8, 24, 5, 30, 0, 0, time.UTC))
if err != nil {
t.Fatalf("NextRun: %v", err)
}
if want := time.Date(2026, 8, 24, 6, 0, 0, 0, time.UTC); !got.Equal(want) {
t.Fatalf("UTC NextRun = %v, want %v UTC", got, want)
}
}
func TestScheduleCronFirstRun(t *testing.T) {
t.Run("anchored on Start", func(t *testing.T) {
s := Schedule{
Kind: ScheduleCron,
Cron: "0 12 * * *",
Start: zoned(2026, 8, 24, 9, 0, 0),
}
want := zoned(2026, 8, 24, 12, 0, 0)
got, err := s.FirstRun(time.Date(2026, 8, 24, 6, 0, 0, 0, testZone))
if err != nil {
t.Fatalf("FirstRun: %v", err)
}
if !got.Equal(want) {
t.Fatalf("FirstRun = %v, want %v", got, want)
}
})
t.Run("zero Start anchors on now", func(t *testing.T) {
s := Schedule{Kind: ScheduleCron, Cron: "0 12 * * *"}
now := zoned(2026, 8, 24, 12, 30, 0)
want := zoned(2026, 8, 25, 12, 0, 0)
got, err := s.FirstRun(now)
if err != nil {
t.Fatalf("FirstRun: %v", err)
}
if !got.Equal(want) {
t.Fatalf("FirstRun(%v) = %v, want %v", now, got, want)
}
})
}
func TestScheduleCronValidate(t *testing.T) {
t.Run("empty cron is rejected", func(t *testing.T) {
err := Schedule{Kind: ScheduleCron}.Validate()
if !errors.Is(err, ErrInvalidSpec) {
t.Fatalf("Validate() = %v, want ErrInvalidSpec", err)
}
})
t.Run("valid expressions pass", func(t *testing.T) {
for _, expr := range []string{"*/15 * * * *", "0 9-17/2 * * *", "@daily", "@yearly"} {
if err := (Schedule{Kind: ScheduleCron, Cron: expr}).Validate(); err != nil {
t.Fatalf("Validate(%q) = %v, want nil", expr, err)
}
}
})
}
func TestScheduleCronInvalidExpressions(t *testing.T) {
tests := []struct {
name string
expr string
}{
{name: "minute out of range", expr: "61 * * * *"},
{name: "hour out of range", expr: "* 24 * * *"},
{name: "day of month out of range", expr: "0 0 32 * *"},
{name: "month out of range", expr: "0 0 * 13 *"},
{name: "day of week out of range", expr: "0 0 * * 7"},
{name: "too few fields", expr: "* * * *"},
{name: "too many fields", expr: "* * * * * *"},
{name: "non-numeric field", expr: "banana * * * *"},
{name: "zero step", expr: "*/0 * * * *"},
{name: "empty", expr: ""},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
s := Schedule{Kind: ScheduleCron, Cron: tc.expr}
if err := s.Validate(); !errors.Is(err, ErrInvalidSpec) {
t.Errorf("Validate() = %v, want ErrInvalidSpec", err)
}
_, err := s.FirstRun(zoned(2026, 8, 24, 12, 0, 0))
if !errors.Is(err, ErrInvalidSpec) {
t.Errorf("FirstRun err = %v, want ErrInvalidSpec", err)
}
_, err = s.NextRun(zoned(2026, 8, 24, 12, 0, 0))
if !errors.Is(err, ErrInvalidSpec) {
t.Errorf("NextRun err = %v, want ErrInvalidSpec", err)
}
})
}
}
+54
View File
@@ -0,0 +1,54 @@
package storecontract
import (
"fmt"
"strconv"
"strings"
"time"
)
// EventCursorLayout is the fixed-width UTC layout every persisted event's at
// column and every EventsSince cursor is built with. Fixed width is the whole
// point: time.RFC3339Nano trims trailing zeros, so a whole-second row
// ("...05Z") and a full-precision row ("...05.123456789Z") would compare out
// of chronological order as strings. With nine fractional digits always
// present, lexicographic order is chronological order. It mirrors edastore's
// capturedAtLayout, which exists for the same reason; the two stores now share
// this rule.
const EventCursorLayout = "2006-01-02T15:04:05.000000000Z"
// cursorSeparator joins the sort key and the row id inside a cursor. The sort
// key never contains it, so splitting on the last occurrence is unambiguous.
const cursorSeparator = "|"
// cursorIDWidth zero-pads the row id so the whole cursor is lexicographically
// sortable: the fixed-width sort key is followed by a fixed-width tie-break,
// and string comparison of two cursors is the total order (key, id).
const cursorIDWidth = 20
// EventCursor returns the opaque resume cursor for an event that happened at
// at with row id id. The cursor is a string so EventSource can carry it
// verbatim in its id: field and echo it back as the Last-Event-ID header; it
// is opaque to every consumer except EventsSince.
func EventCursor(at time.Time, id int64) string {
return at.UTC().Format(EventCursorLayout) + cursorSeparator + fmt.Sprintf("%0*d", cursorIDWidth, id)
}
// ParseEventCursor splits a cursor back into its sort key (the fixed-width at
// string) and row id. ok is false for an empty or malformed cursor, which
// means "from the beginning" -- the store must not treat a bad resume point as
// an error worth failing a feed over.
func ParseEventCursor(cursor string) (at string, id int64, ok bool) {
if cursor == "" {
return "", 0, false
}
i := strings.LastIndex(cursor, cursorSeparator)
if i < 0 {
return "", 0, false
}
id, err := strconv.ParseInt(cursor[i+1:], 10, 64)
if err != nil {
return "", 0, false
}
return cursor[:i], id, true
}
+43 -13
View File
@@ -32,10 +32,12 @@ import (
// Consumers depend on TaskStore, never on a concrete type.
type TaskStore interface {
TaskLifecycle
TaskParker
TaskEvents
TaskQueries
TaskArchiver
TaskRetryer
RemediationStarter
}
// TaskLifecycle manages the core task state machine and enqueuing.
@@ -53,6 +55,16 @@ type TaskLifecycle interface {
RecoverStale(ctx context.Context) (int64, error)
}
// TaskParker is the classified park write, kept off TaskLifecycle so that
// interface stays under the repo's 8-method cap. It mirrors Transition with
// a park class attached (taskstate.ParkClass); the class is normalized
// store-side, so an empty or unknown value becomes needs_human rather than
// an error -- a park that predates classification must not fail because its
// caller did not know the vocabulary.
type TaskParker interface {
ParkTask(ctx context.Context, taskID int64, from, detail, class string) error
}
// TaskArchiver removes one terminal task's local record with an optimistic
// status guard. It is separate from the already broad lifecycle contract so
// consumers that only run tasks do not acquire an operator-only capability.
@@ -66,6 +78,22 @@ type TaskRetryer interface {
RetryTask(ctx context.Context, taskID int64, fromStatus, workflow string) error
}
// RemediationStarter queues a review-triggered remediation for an
// Archie-owned open-PR task: one guarded transition that carries the
// JSON-encoded review unit in the same write, so a claimed remediation
// always has its input. UpdateReviewPayload appends late-arriving comments
// to a still-queued unit. Both guards are the reaction consumer's dedup and
// are documented in docs/prds/pr-review-remediation.md decisions 3 and 5.
type RemediationStarter interface {
BeginRemediation(ctx context.Context, taskID int64, payload string) error
UpdateReviewPayload(ctx context.Context, taskID int64, payload string) error
// SetReviewCursors persists the poll backstop's per-task review and
// comment high-water marks (pr-review-remediation.md decision 2). The
// pr_open guard is part of the contract: cursors only move while no
// remediation run owns the task.
SetReviewCursors(ctx context.Context, taskID, reviewCursor, commentCursor int64) error
}
// TaskQueries groups read-only task accessors.
type TaskQueries interface {
TaskByIssue(ctx context.Context, owner, repo string, number int) (*task.Task, error)
@@ -80,7 +108,7 @@ type TaskQueries interface {
// TaskEvents groups observability and lifecycle methods.
type TaskEvents interface {
InsertEvent(ctx context.Context, e events.Event) (int64, error)
EventsSince(ctx context.Context, sinceID int64, limit int) ([]events.Event, error)
EventsSince(ctx context.Context, cursor string, limit int) ([]events.Event, error)
TaskEvents(ctx context.Context, taskID int64) ([]events.Event, error)
WorkflowStats(ctx context.Context) ([]WorkflowStat, error)
StageStats(ctx context.Context) ([]StageStat, error)
@@ -94,7 +122,7 @@ type TaskEvents interface {
// should not acquire the full task-lifecycle surface, mirroring why
// TaskArchiver is split out above. See docs/prds/event-capture-storage.md.
type CaptureStore interface {
InsertCapture(ctx context.Context, c CapturedEvent, retention time.Duration, maxEvents int) (int64, error)
InsertCapture(ctx context.Context, c CapturedEvent, retention time.Duration, maxEvents int) (string, error)
ListCaptures(ctx context.Context, limit int) ([]CapturedEvent, error)
}
@@ -142,11 +170,11 @@ type ApplyStatusStore interface {
// surface, not the full task or capture APIs. See
// docs/prds/payload-field-mapping.md.
type MappingStore interface {
InsertMapping(ctx context.Context, m mapping.Mapping) (int64, error)
GetMapping(ctx context.Context, id int64) (*mapping.Mapping, error)
InsertMapping(ctx context.Context, m mapping.Mapping) (string, error)
GetMapping(ctx context.Context, id string) (*mapping.Mapping, error)
ListMappings(ctx context.Context) ([]mapping.Mapping, error)
UpdateMapping(ctx context.Context, m mapping.Mapping) error
DeleteMapping(ctx context.Context, id int64) error
DeleteMapping(ctx context.Context, id string) error
}
// BindingStore persists playbook bindings (t2db.4 Phase B): CRUD and the
@@ -156,12 +184,12 @@ type MappingStore interface {
// BindingDispatcher; the daemon depends on both. See
// docs/prds/playbook-binding.md.
type BindingStore interface {
InsertBinding(ctx context.Context, b binding.Binding) (int64, error)
GetBinding(ctx context.Context, id int64) (*binding.Binding, error)
InsertBinding(ctx context.Context, b binding.Binding) (string, error)
GetBinding(ctx context.Context, id string) (*binding.Binding, error)
ListBindings(ctx context.Context) ([]binding.Binding, error)
UpdateBinding(ctx context.Context, b binding.Binding) error
DeleteBinding(ctx context.Context, id int64) error
ApproveBinding(ctx context.Context, id int64) error
DeleteBinding(ctx context.Context, id string) error
ApproveBinding(ctx context.Context, id string) error
}
// BindingDispatcher is the dispatch-loop surface over the bindings store:
@@ -174,9 +202,11 @@ type BindingDispatcher interface {
ArmedBindingsForSource(ctx context.Context, source string) ([]binding.Binding, error)
RecordDispatch(
ctx context.Context,
bindingID int64,
bindingID string,
bindingVersion int64,
captureID int64,
captureID string,
// taskID addresses the SQLite-owned task tables, which are not
// migrating: it stays an integer on purpose.
taskID int64,
) error
ListUndispatchedCaptures(ctx context.Context, sources []string, limit int) ([]CapturedEvent, error)
@@ -187,7 +217,7 @@ type BindingDispatcher interface {
// keeps the lifecycle surface narrow (8 methods, the interfacebloat limit)
// and keeps the binding-specific shape on the binding interfaces.
type BindingTaskCreator interface {
EnqueueBindingTask(ctx context.Context, owner, repo, title, body, wf, identity string, bindingID int64, bindingVersion int) (*task.Task, error)
EnqueueBindingTask(ctx context.Context, owner, repo, title, body, wf, identity, bindingID string, bindingVersion int) (*task.Task, error)
}
// PlaybookDispatcher is the idempotency-ledger surface for side-effecting
@@ -231,7 +261,7 @@ type TaskLogStore interface {
// no forge/task association -- just what arrived, from where, and when.
// See docs/prds/event-capture-storage.md.
type CapturedEvent struct {
ID int64 `json:"id"`
ID string `json:"id"`
ReceivedAt time.Time `json:"received_at"`
Source string `json:"source"`
RemoteAddr string `json:"remote_addr"`
+9 -6
View File
@@ -155,19 +155,22 @@ func StageResumeWorktree() Stage {
// StageRemediationRoundCap enforces the hard stop on an unbounded
// remediate/re-review exchange (decision 5, "bounding the exchange").
// Task.RetryCount doubles as the remediation round counter here: on the
// Task.RemediationRounds is the remediation's own budget, separate from
// RetryCount (the operator's): one shared counter made N operator retries
// eat the review-remediation budget and vice versa, and let a repo-level
// round cap re-park a task an operator had just legally retried. On the
// cap it parks the task and posts one comment explaining why, without
// running the builder; under the cap it counts this round and proceeds.
func StageRemediationRoundCap() Stage {
return Stage{Name: "round-cap", Run: func(ctx context.Context, tc *TaskContext) error {
maxRounds := tc.Repo.EffectiveMaxRetries(tc.Cfg.MaxRetries)
if maxRounds > 0 && tc.Task.RetryCount >= maxRounds {
detail := fmt.Sprintf("remediation round cap reached (%d/%d); stopping and parking for an operator", tc.Task.RetryCount, maxRounds)
if maxRounds > 0 && tc.Task.RemediationRounds >= maxRounds {
detail := fmt.Sprintf("remediation round cap reached (%d/%d); stopping and parking for an operator", tc.Task.RemediationRounds, maxRounds)
postRemediationComment(ctx, tc, "Archie has stopped remediating this review: "+detail+".")
tc.Outcome = Outcome{Status: StatusParked, Detail: clip(detail, remediationRoundCapBytes)}
return nil
}
tc.Task.RetryCount++
tc.Task.RemediationRounds++
return nil
}}
}
@@ -272,7 +275,7 @@ func StageRemediationReply() Stage {
if tc.BuildNoChanges {
summary = "Reviewed -- no code change was required."
}
reply := fmt.Sprintf("%s\n\n---\n*archie remediation, round %d*", summary, tc.Task.RetryCount)
reply := fmt.Sprintf("%s\n\n---\n*archie remediation, round %d*", summary, tc.Task.RemediationRounds)
if id, ok := tc.reviewUnit.replyTarget(); ok {
if err := tc.Forge.ReplyToReview(ctx, tc.Task.Owner, tc.Task.Repo, tc.Task.PRNumber, id, reply); err != nil {
@@ -283,7 +286,7 @@ func StageRemediationReply() Stage {
}
tc.Task.ReviewPayload = ""
tc.Outcome = Outcome{Status: StatusPROpen, Detail: fmt.Sprintf("remediated review round %d", tc.Task.RetryCount)}
tc.Outcome = Outcome{Status: StatusPROpen, Detail: fmt.Sprintf("remediated review round %d", tc.Task.RemediationRounds)}
return nil
}}
}
+11 -11
View File
@@ -70,14 +70,14 @@ func TestStageResumeWorktreeResumesOntoTheTaskBranch(t *testing.T) {
func TestStageRemediationRoundCapCountsARoundUnderTheCap(t *testing.T) {
forge := &fakeForge{}
tc := &TaskContext{
Task: &Task{ID: 1, RetryCount: 1}, Repo: config.Repo{MaxRetries: 3}, Forge: forge,
Task: &Task{ID: 1, RemediationRounds: 1}, Repo: config.Repo{MaxRetries: 3}, Forge: forge,
Log: slog.New(slog.DiscardHandler),
}
if err := StageRemediationRoundCap().Run(t.Context(), tc); err != nil {
t.Fatalf("StageRemediationRoundCap: %v", err)
}
if tc.Task.RetryCount != 2 {
t.Fatalf("RetryCount = %d, want 2", tc.Task.RetryCount)
if tc.Task.RemediationRounds != 2 {
t.Fatalf("RemediationRounds = %d, want 2", tc.Task.RemediationRounds)
}
if tc.Outcome.Status != "" {
t.Fatalf("Outcome = %+v, want zero value (workflow continues)", tc.Outcome)
@@ -90,14 +90,14 @@ func TestStageRemediationRoundCapCountsARoundUnderTheCap(t *testing.T) {
func TestStageRemediationRoundCapParksAtTheCapAndPostsOneComment(t *testing.T) {
forge := &fakeForge{}
tc := &TaskContext{
Task: &Task{ID: 1, RetryCount: 3, PRNumber: 9}, Repo: config.Repo{MaxRetries: 3}, Forge: forge,
Task: &Task{ID: 1, RemediationRounds: 3, PRNumber: 9}, Repo: config.Repo{MaxRetries: 3}, Forge: forge,
Log: slog.New(slog.DiscardHandler),
}
if err := StageRemediationRoundCap().Run(t.Context(), tc); err != nil {
t.Fatalf("StageRemediationRoundCap: %v", err)
}
if tc.Task.RetryCount != 3 {
t.Fatalf("RetryCount = %d, want unchanged at 3", tc.Task.RetryCount)
if tc.Task.RemediationRounds != 3 {
t.Fatalf("RemediationRounds = %d, want unchanged at 3", tc.Task.RemediationRounds)
}
if tc.Outcome.Status != StatusParked {
t.Fatalf("Outcome.Status = %q, want parked", tc.Outcome.Status)
@@ -109,7 +109,7 @@ func TestStageRemediationRoundCapParksAtTheCapAndPostsOneComment(t *testing.T) {
func TestStageRemediationRoundCapZeroMeansUnlimited(t *testing.T) {
tc := &TaskContext{
Task: &Task{ID: 1, RetryCount: 50}, Repo: config.Repo{}, Cfg: config.Config{MaxRetries: 0},
Task: &Task{ID: 1, RemediationRounds: 50}, Repo: config.Repo{}, Cfg: config.Config{MaxRetries: 0},
Forge: &fakeForge{}, Log: slog.New(slog.DiscardHandler),
}
if err := StageRemediationRoundCap().Run(t.Context(), tc); err != nil {
@@ -118,8 +118,8 @@ func TestStageRemediationRoundCapZeroMeansUnlimited(t *testing.T) {
if tc.Outcome.Status == StatusParked {
t.Fatal("Outcome = parked, want no cap enforced when max_retries is unset")
}
if tc.Task.RetryCount != 51 {
t.Fatalf("RetryCount = %d, want 51", tc.Task.RetryCount)
if tc.Task.RemediationRounds != 51 {
t.Fatalf("RemediationRounds = %d, want 51", tc.Task.RemediationRounds)
}
}
@@ -240,8 +240,8 @@ func TestRemediateEndToEndAddressesCommentsAndReplies(t *testing.T) {
if forge.replyCommentID != 10 {
t.Fatalf("replyCommentID = %d, want 10", forge.replyCommentID)
}
if task.RetryCount != 1 {
t.Fatalf("RetryCount = %d, want 1 (one round consumed)", task.RetryCount)
if task.RemediationRounds != 1 {
t.Fatalf("RemediationRounds = %d, want 1 (one round consumed)", task.RemediationRounds)
}
if task.ReviewPayload != "" {
t.Fatalf("ReviewPayload = %q, want cleared", task.ReviewPayload)
@@ -0,0 +1,56 @@
package workflow
import (
"fmt"
"strings"
)
// RenderMarkdown renders an adversarial review report as the artifact source
// the collaborative editor publishes. It is a pure function over the report:
// no I/O, no infrastructure, so the rendered form is testable in isolation.
//
// A completed review renders its summary, every finding as its own subsection
// (file, line, verdict, level, failure scenario, and the mechanical suggestion
// and disposition when present) and the verified properties as a "checked
// clean" list. A review that did not run renders only its reason, because a
// report that never executed has no findings or checks to stand behind.
func (r ReviewReport) RenderMarkdown(title string) string {
var b strings.Builder
fmt.Fprintf(&b, "# %s\n\n", title)
if r.Status == ReviewStatusNotRun || (r.SkipReason != "" && len(r.Findings) == 0 && len(r.Checked) == 0) {
fmt.Fprintf(&b, "> This review did not run: %s\n", r.SkipReason)
return strings.TrimRight(b.String(), "\n") + "\n"
}
if r.Summary != "" {
b.WriteString(r.Summary)
b.WriteString("\n\n")
}
if len(r.Findings) > 0 {
b.WriteString("## Findings\n\n")
for _, f := range r.Findings {
fmt.Fprintf(&b, "### %s:%d — %s (%s)\n\n", f.File, f.Line, f.Level, f.Verdict)
fmt.Fprintf(&b, "**Defect:** %s\n\n", f.Defect)
if f.FailureScenario != "" {
fmt.Fprintf(&b, "**Failure scenario:** %s\n\n", f.FailureScenario)
}
if f.Suggestion != "" {
fmt.Fprintf(&b, "Suggested fix: %s\n\n", f.Suggestion)
}
if f.Disposition != "" {
fmt.Fprintf(&b, "Disposition: %s\n\n", f.Disposition)
}
}
}
if len(r.Checked) > 0 {
b.WriteString("## Checked clean\n\n")
for _, c := range r.Checked {
fmt.Fprintf(&b, "- %s — %s\n", c.Property, c.Evidence)
}
}
return strings.TrimRight(b.String(), "\n") + "\n"
}
@@ -0,0 +1,78 @@
package workflow
import (
"strings"
"testing"
)
func mdFixture() ReviewReport {
disposition := ReviewDisposition("fixed")
return ReviewReport{
Status: ReviewStatusCompleted,
Summary: "The nil-deref path is reachable from a malformed payload.",
Findings: []ReviewFinding{
{
File: "handler.go", Line: 42, Defect: "nil deref on empty payload",
FailureScenario: "POST with a body lacking the field crashes the handler.",
Suggestion: "guard the field before use", Verdict: ReviewVerdictConfirmed,
Level: ReviewLevelError, Category: "correctness", Disposition: disposition,
},
{
File: "store.go", Line: 9, Defect: "query loses the filter",
FailureScenario: "paged reads return rows from other scopes",
Verdict: ReviewVerdictPlausible, Level: ReviewLevelWarn,
},
},
Checked: []ReviewCheck{
{Property: "nil-safety of Foo callers", Evidence: "read all 4 callers; each nil-checks"},
},
}
}
func TestReviewReportRendersFindingsAsMarkdown(t *testing.T) {
got := mdFixture().RenderMarkdown("Review of acme/widget#42")
for _, want := range []string{
"# Review of acme/widget#42",
"The nil-deref path is reachable",
"### handler.go:42",
"**Defect:** nil deref on empty payload",
"**Failure scenario:** POST with a body lacking the field crashes the handler.",
"error (confirmed)",
"Suggested fix: guard the field before use",
"Disposition: fixed",
"### store.go:9",
"warn (plausible)",
"## Checked clean",
"- nil-safety of Foo callers — read all 4 callers; each nil-checks",
} {
if !strings.Contains(got, want) {
t.Fatalf("rendered report missing %q:\n%s", want, got)
}
}
}
func TestReviewReportRendersNotRunStatus(t *testing.T) {
report := NewNotRunReviewReport("no reviewer model configured")
got := report.RenderMarkdown("Review of acme/widget#42")
if !strings.Contains(got, "no reviewer model configured") {
t.Fatalf("skip reason missing:\n%s", got)
}
if strings.Contains(got, "## Findings") || strings.Contains(got, "## Checked clean") {
t.Fatalf("a not-run report must not render finding or check sections:\n%s", got)
}
}
func TestReviewReportRendersACleanReview(t *testing.T) {
report := ReviewReport{
Status: ReviewStatusCompleted,
Summary: "No defects found.",
Checked: []ReviewCheck{{Property: "p", Evidence: "e"}},
}
got := report.RenderMarkdown("Review")
if strings.Contains(got, "### ") {
t.Fatalf("a zero-finding review must not render finding sections:\n%s", got)
}
if !strings.Contains(got, "No defects found.") || !strings.Contains(got, "- p — e") {
t.Fatalf("summary and checks missing:\n%s", got)
}
}
+22 -4
View File
@@ -64,9 +64,16 @@ type Task struct {
// (parking-to-queued transitions). When it reaches the configured
// max_retries the daemon moves the task to StatusDead.
RetryCount int `json:"retry_count"`
// WatchCommentID: replies to the issue after this comment are the
// human input a waiting_human task is blocked on.
// WatchCommentID is the poll backstop's high-water mark over forge
// review-comment IDs for this task (pr-review-remediation.md decision
// 2's persisted per-task cursor; the comment-watch design it was
// created for never shipped, and the field carries the cursor now).
WatchCommentID int64 `json:"watch_comment_id"`
// ReviewCursor is the poll backstop's high-water mark over forge
// review IDs. It is deliberately separate from WatchCommentID: review
// and comment IDs are independent forge sequences, and one combined
// cursor would silently skip reviews once a larger comment ID landed.
ReviewCursor int64 `json:"review_cursor"`
// Source is "forge" (default; a real forge issue backs this task) or
// "chat" (created via /spawn with no forge issue). Workflow stages
// and daemon reconciliation must skip forge-only operations (issue
@@ -82,8 +89,8 @@ type Task struct {
// from a playbook binding dispatch (t2db.4 Phase B). They record
// provenance: which binding fired this task and at what version, so
// later edits to the binding cannot silently rewrite history.
BindingID int64 `json:"binding_id"`
BindingVersion int `json:"binding_version"`
BindingID string `json:"binding_id"`
BindingVersion int `json:"binding_version"`
// ReviewPayload is the JSON-encoded review unit (the forge review's
// actionable comments) the remediate workflow's current run must
// address. The daemon's reaction consumer injects it before queuing a
@@ -93,6 +100,17 @@ type Task struct {
// the remediation round counter for this same task, bounded by the
// repo's existing max_retries (decision 5's round cap).
ReviewPayload string `json:"review_payload"`
// ParkClass is the producer-recorded answer to "what kind of
// intervention does this park need?" (taskstate.ParkClass). Set at the
// park site, never inferred from reason text; needs_human is the
// default an unclassified park reads as.
ParkClass string `json:"park_class"`
// RemediationRounds counts review-triggered remediation rounds,
// bounded by the repo's max_retries (pr-review-remediation.md
// decision 5). Deliberately separate from RetryCount, the operator
// budget: one shared counter made N operator retries eat the
// review-remediation budget and vice versa.
RemediationRounds int `json:"remediation_rounds"`
// CreatedAt and UpdatedAt are the SQLite row timestamps, exposed so
// callers can show a task's age and last activity. They are written by
// column defaults and the UPDATE statements, never by the caller.
+9
View File
@@ -105,6 +105,15 @@ const (
// trigger. data: session, channel.
KindTurnCompleted = "turn_completed"
// EDA edit activity (bindings and mappings on the captures store). Each
// successful write on the State Store's PocketBase tables emits one
// event through the same task-DB path capture arrival uses, so a
// dashboard edit is visible on the activity stream without a manual
// refresh. data: id (the edited record), action (create, update,
// approve, delete).
KindBindingChanged = "binding_changed"
KindMappingChanged = "mapping_changed"
// KindUpdateReport carries the phase-2 outcome of a dashboard-initiated
// update -- whether the restarted daemon came back up healthy and on
// the version it claimed, relayed once on the boot that finds the
+9 -1
View File
@@ -123,6 +123,7 @@ type Review struct {
ID int64
Author string
State string // one of the ReviewState* constants
Body string // the review's own top-level summary; empty for a bare verdict
SubmittedAt time.Time
}
@@ -131,7 +132,14 @@ type Review struct {
// the whole file. InReplyTo is the parent comment ID on GitHub; Gitea's
// inline comments are flat under a review, so it is 0 there.
type ReviewComment struct {
ID int64
ID int64
// ReviewID is the review this comment belongs to. It is what lets a
// comment be collected into its review's remediation unit instead of
// starting one of its own (pr-review-remediation.md decision 5); a
// standalone comment carries 0. GitHub carries it on the comment;
// Gitea's flat comment list is walked per review, so the mapping comes
// from the walk.
ReviewID int64
Author string
Body string
Path string
+2
View File
@@ -188,6 +188,7 @@ func (c *GiteaClient) ListReviews(ctx context.Context, owner, repo string, numbe
ID: r.ID,
Author: giteaReviewAuthor(r.Reviewer),
State: normalizeGiteaReviewState(r.State),
Body: r.Body,
SubmittedAt: r.Submitted,
})
}
@@ -219,6 +220,7 @@ func (c *GiteaClient) ListReviewComments(ctx context.Context, owner, repo string
}
out = append(out, ReviewComment{
ID: cm.ID,
ReviewID: rv.ID,
Author: giteaReviewAuthor(cm.Reviewer),
Body: cm.Body,
Path: cm.Path,
+2
View File
@@ -207,6 +207,7 @@ func (c *GitHubClient) ListReviews(ctx context.Context, owner, repo string, numb
ID: r.GetID(),
Author: r.GetUser().GetLogin(),
State: normalizeReviewState(r.GetState()),
Body: r.GetBody(),
SubmittedAt: r.GetSubmittedAt().Time,
})
}
@@ -237,6 +238,7 @@ func (c *GitHubClient) ListReviewComments(ctx context.Context, owner, repo strin
}
out = append(out, ReviewComment{
ID: cm.GetID(),
ReviewID: cm.GetPullRequestReviewID(),
Author: cm.GetUser().GetLogin(),
Body: cm.GetBody(),
Path: cm.GetPath(),
+201
View File
@@ -0,0 +1,201 @@
package webhook
import (
"context"
"encoding/json"
"net/http"
"net/http/httptest"
"testing"
"github.com/google/go-github/v78/github"
"github.com/samcharles93/archie-core/internal/domain/workintake"
)
// reviewEvent builds a signed pull_request_review delivery, GitHub's
// low-latency path for "a human reacted to archie's PR" (decision 2).
func reviewEvent(t *testing.T, action string, mutate func(*github.PullRequestReviewEvent)) *http.Request {
t.Helper()
ev := &github.PullRequestReviewEvent{
Action: new(action),
Review: &github.PullRequestReview{
ID: new(int64(7)),
State: new("requested_changes"),
Body: new("please fix the loop"),
User: &github.User{Login: new("alice")},
},
PullRequest: &github.PullRequest{Number: new(42)},
Repo: &github.Repository{
Name: new("widgets"),
Owner: &github.User{Login: new("acme")},
},
}
if mutate != nil {
mutate(ev)
}
payload, err := json.Marshal(ev)
if err != nil {
t.Fatal(err)
}
return signedRequest(t, testSecret, "pull_request_review", payload)
}
func reviewCommentEvent(t *testing.T, action string, mutate func(*github.PullRequestReviewCommentEvent)) *http.Request {
t.Helper()
ev := &github.PullRequestReviewCommentEvent{
Action: new(action),
Comment: &github.PullRequestComment{
ID: new(int64(11)),
PullRequestReviewID: new(int64(7)),
Body: new("also this"),
Path: new("x.go"),
Line: new(3),
User: &github.User{Login: new("bob")},
},
PullRequest: &github.PullRequest{Number: new(42)},
Repo: &github.Repository{
Name: new("widgets"),
Owner: &github.User{Login: new("acme")},
},
}
if mutate != nil {
mutate(ev)
}
payload, err := json.Marshal(ev)
if err != nil {
t.Fatal(err)
}
return signedRequest(t, testSecret, "pull_request_review_comment", payload)
}
func serveReaction(t *testing.T, r *Receiver, req *http.Request) (*httptest.ResponseRecorder, []workintake.ReviewCommentEnvelope) {
t.Helper()
var published []workintake.ReviewCommentEnvelope
r.reactionPublish = func(_ context.Context, e workintake.ReviewCommentEnvelope) error {
published = append(published, e)
return nil
}
rec := httptest.NewRecorder()
r.ServeHTTP(rec, req)
return rec, published
}
func newReactionReceiver() *Receiver {
return New(testSecret, "label", testLabel, testBot, nil, nil, nil)
}
func TestReceiverPublishesASubmittedReviewAsAReaction(t *testing.T) {
r := newReactionReceiver()
rec, published := serveReaction(t, r, reviewEvent(t, "submitted", nil))
if rec.Code != http.StatusAccepted {
t.Fatalf("status = %d, want 202", rec.Code)
}
if len(published) != 1 {
t.Fatalf("published = %d, want 1", len(published))
}
e := published[0]
if e.Kind != workintake.ReviewReactionReview || e.ReviewID != 7 || e.Owner != "acme" || e.Repo != "widgets" || e.PRNumber != 42 {
t.Errorf("reaction = %+v, want review 7 on acme/widgets#42", e)
}
if e.State != "requested_changes" || e.Body != "please fix the loop" || e.Author != "alice" {
t.Errorf("reaction content = %+v, want the review's own state/body/author", e)
}
// The idempotency key is kinded (decision 3): a review ID and a comment
// ID come from independent forge sequences and must never collide.
if e.IdempotencyKey() == "" {
t.Error("reaction carried no idempotency key")
}
}
func TestReceiverPublishesACreatedCommentAsAReaction(t *testing.T) {
r := newReactionReceiver()
rec, published := serveReaction(t, r, reviewCommentEvent(t, "created", nil))
if rec.Code != http.StatusAccepted {
t.Fatalf("status = %d, want 202", rec.Code)
}
if len(published) != 1 {
t.Fatalf("published = %d, want 1", len(published))
}
e := published[0]
if e.Kind != workintake.ReviewReactionComment || e.CommentID != 11 || e.ReviewID != 7 {
t.Errorf("reaction = %+v, want comment 11 collected under review 7", e)
}
}
func TestReceiverIgnoresNonActionReviewActivity(t *testing.T) {
tests := []struct {
name string
kind string
action string
}{
{"dismissed review", "review", "dismissed"},
{"edited review", "review", "edited"},
{"deleted review", "review", "deleted"},
{"edited comment", "comment", "edited"},
{"deleted comment", "comment", "deleted"},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
r := newReactionReceiver()
var req *http.Request
if tt.kind == "review" {
req = reviewEvent(t, tt.action, nil)
} else {
req = reviewCommentEvent(t, tt.action, nil)
}
rec, published := serveReaction(t, r, req)
if rec.Code != http.StatusAccepted {
t.Fatalf("status = %d, want 202", rec.Code)
}
if len(published) != 0 {
t.Errorf("published %d reactions for action %q", len(published), tt.action)
}
})
}
}
func TestReceiverReactionWithoutTheCapabilityIsUntouched(t *testing.T) {
// A receiver composed without the reaction publisher (nil) must not
// panic or publish when a review event arrives: the reaction path is an
// optional capability, the issue path is the receiver's core contract.
r := New(testSecret, "label", testLabel, testBot, nil, nil, nil)
rec := httptest.NewRecorder()
r.ServeHTTP(rec, reviewEvent(t, "submitted", nil))
if rec.Code != http.StatusAccepted {
t.Fatalf("status = %d, want 202", rec.Code)
}
}
func TestReceiverRateLimitsReactionDeliveries(t *testing.T) {
r := newReactionReceiver()
// Drive the limiter to its per-window ceiling with one remote, then
// assert the next reaction from that remote is refused with 429 while a
// different remote still passes.
remote := "10.0.0.1:1234"
for i := range reactionRateLimit {
req := reviewEvent(t, "submitted", nil)
req.RemoteAddr = remote
rec, _ := serveReaction(t, r, req)
if rec.Code != http.StatusAccepted {
t.Fatalf("delivery %d within the window: status = %d, want 202", i+1, rec.Code)
}
}
req := reviewEvent(t, "submitted", nil)
req.RemoteAddr = remote
rec, published := serveReaction(t, r, req)
if rec.Code != http.StatusTooManyRequests {
t.Fatalf("over-limit status = %d, want 429", rec.Code)
}
if len(published) != 0 {
t.Errorf("over-limit delivery published %d reactions", len(published))
}
otherReq := reviewEvent(t, "submitted", nil)
otherReq.RemoteAddr = "10.0.0.2:1234"
rec, published = serveReaction(t, r, otherReq)
if rec.Code != http.StatusAccepted || len(published) != 1 {
t.Errorf("different remote blocked: status = %d, published = %d", rec.Code, len(published))
}
}
+176 -31
View File
@@ -55,37 +55,67 @@ const maxBodyBytes = 1 << 20 // 1 MiB
// (*daemon.Daemon).PublishTask, the same enqueue path the poller uses.
type PublishFunc func(ctx context.Context, task workintake.TaskEnvelope) error
// ReactionPublishFunc delivers one decoded review reaction to the reaction
// stream (pr-review-remediation.md decision 2's webhook producer). The
// composition root wires it to PublishUnique against the envelope's reaction
// subject, so a webhook delivery and a poll record of the same review dedup
// on the envelope's source-independent key. The reaction path carries no
// dispatch predicate: eligibility is the consumer's owned-PR lookup.
type ReactionPublishFunc func(ctx context.Context, reaction workintake.ReviewCommentEnvelope) error
// reactionRateLimit bounds reaction deliveries per remote source per window
// (decision 6's per-source rate limiting, due now that the receiver carries a
// second event family). It guards spend, not authorization: the owned-task
// guard at the consumer remains the authorization boundary.
const (
reactionRateLimit = 60
reactionRateWindow = time.Minute
reactionRateBucketTTL = 5 * time.Minute
)
// Receiver is the HTTP handler for forge webhooks. It verifies the signature,
// decodes the event, applies the shared dispatch predicate, and publishes
// matched issues.
type Receiver struct {
secret string
trigger string
label string
botUser string
publish PublishFunc
log *slog.Logger
secret string
trigger string
label string
botUser string
publish PublishFunc
reactionPublish ReactionPublishFunc
log *slog.Logger
mu sync.Mutex
startedAt time.Time
lastReceivedAt time.Time
deliveries uint64
publishes uint64
mu sync.Mutex
startedAt time.Time
lastReceivedAt time.Time
deliveries uint64
publishes uint64
reactionPublishes uint64
reactionLimiter map[string]*reactionWindow
}
// reactionWindow is one remote's fixed-window rate budget.
type reactionWindow struct {
start time.Time
count int
}
// New returns an unstarted Receiver.
func New(secret, trigger, label, botUser string, publish PublishFunc, log *slog.Logger) *Receiver {
func New(secret, trigger, label, botUser string, publish PublishFunc, reactionPublish ReactionPublishFunc, log *slog.Logger) *Receiver {
if log == nil {
log = slog.New(slog.DiscardHandler)
}
return &Receiver{
secret: secret,
trigger: trigger,
label: label,
botUser: botUser,
publish: publish,
log: log.With("component", "forge-webhook"),
startedAt: time.Now(),
secret: secret,
trigger: trigger,
label: label,
botUser: botUser,
publish: publish,
reactionPublish: reactionPublish,
reactionLimiter: map[string]*reactionWindow{},
log: log.With("component", "forge-webhook"),
startedAt: time.Now(),
}
}
@@ -96,10 +126,11 @@ func New(secret, trigger, label, botUser string, publish PublishFunc, log *slog.
// Publishes counts only what the dispatch predicate turned into work.
// LastReceivedAt is nil until the first authenticated delivery arrives.
type Status struct {
StartedAt time.Time `json:"started_at"`
LastReceivedAt *time.Time `json:"last_received_at"`
Deliveries uint64 `json:"deliveries"`
Publishes uint64 `json:"publishes"`
StartedAt time.Time `json:"started_at"`
LastReceivedAt *time.Time `json:"last_received_at"`
Deliveries uint64 `json:"deliveries"`
Publishes uint64 `json:"publishes"`
ReactionPublishes uint64 `json:"reaction_publishes"`
}
// Status returns a snapshot of the receiver's activity counters.
@@ -107,9 +138,10 @@ func (r *Receiver) Status() Status {
r.mu.Lock()
defer r.mu.Unlock()
s := Status{
StartedAt: r.startedAt,
Deliveries: r.deliveries,
Publishes: r.publishes,
StartedAt: r.startedAt,
Deliveries: r.deliveries,
Publishes: r.publishes,
ReactionPublishes: r.reactionPublishes,
}
if !r.lastReceivedAt.IsZero() {
last := r.lastReceivedAt
@@ -136,6 +168,13 @@ func (r *Receiver) recordPublish() {
r.publishes++
}
// recordReactionPublish marks one delivery as having produced a reaction.
func (r *Receiver) recordReactionPublish() {
r.mu.Lock()
defer r.mu.Unlock()
r.reactionPublishes++
}
// ServeHTTP handles one forge webhook delivery. GitHub only ever POSTs here,
// so any GET is answered with the receiver's Status instead -- an operator
// (or a monitor) can curl the same address the webhook is configured against
@@ -177,14 +216,23 @@ func (r *Receiver) ServeHTTP(w http.ResponseWriter, req *http.Request) {
// independent of whether it turns out to be dispatch-eligible.
r.recordDelivery()
issueEvent, ok := event.(*github.IssuesEvent)
if !ok {
// Not an issue event (ping, pull_request, etc.). Acknowledge and
// ignore -- this receiver only turns issue activity into work.
switch e := event.(type) {
case *github.IssuesEvent:
r.serveIssueEvent(w, req, e)
case *github.PullRequestReviewEvent:
r.serveReviewEvent(w, req, e)
case *github.PullRequestReviewCommentEvent:
r.serveReviewCommentEvent(w, req, e)
default:
// Not an event this receiver decodes (ping, push, etc.).
// Acknowledge and ignore.
w.WriteHeader(http.StatusAccepted)
return
}
}
// serveIssueEvent is the receiver's original contract: an eligible issue
// event becomes a task envelope on the task path.
func (r *Receiver) serveIssueEvent(w http.ResponseWriter, req *http.Request, issueEvent *github.IssuesEvent) {
task, ok := r.taskFromEvent(issueEvent)
if !ok {
// Delivered but not eligible work (PR, closed, unrelated action,
@@ -203,6 +251,103 @@ func (r *Receiver) ServeHTTP(w http.ResponseWriter, req *http.Request) {
w.WriteHeader(http.StatusAccepted)
}
// serveReviewEvent turns a submitted review into a reaction, the webhook
// half of decision 2: the same typed reaction the poller produces, so
// PublishUnique dedups the two sources. Only "submitted" carries a verdict
// or summary to remediate; edited and dismissed restate or withdraw one.
func (r *Receiver) serveReviewEvent(w http.ResponseWriter, req *http.Request, e *github.PullRequestReviewEvent) {
if e.GetAction() != "submitted" || e.GetReview() == nil {
w.WriteHeader(http.StatusAccepted)
return
}
if !r.allowReactionDelivery(req.RemoteAddr) {
r.log.Warn("reaction rate limit exceeded", "remote", req.RemoteAddr)
http.Error(w, "rate limited", http.StatusTooManyRequests)
return
}
if r.reactionPublish == nil {
w.WriteHeader(http.StatusAccepted)
return
}
review := e.GetReview()
reaction := workintake.ReviewCommentEnvelope{
Owner: e.GetRepo().GetOwner().GetLogin(),
Repo: e.GetRepo().GetName(),
PRNumber: e.GetPullRequest().GetNumber(),
Kind: workintake.ReviewReactionReview,
ReviewID: review.GetID(),
Author: review.GetUser().GetLogin(),
State: review.GetState(),
Body: review.GetBody(),
}
r.deliverReaction(w, req, reaction)
}
// serveReviewCommentEvent publishes an inline comment as a reaction. The
// comment carries its parent review's ID, so the consumer can collect it
// into that review's unit (decision 5) rather than starting a round of its
// own.
func (r *Receiver) serveReviewCommentEvent(w http.ResponseWriter, req *http.Request, e *github.PullRequestReviewCommentEvent) {
if e.GetAction() != "created" || e.GetComment() == nil {
w.WriteHeader(http.StatusAccepted)
return
}
if !r.allowReactionDelivery(req.RemoteAddr) {
r.log.Warn("reaction rate limit exceeded", "remote", req.RemoteAddr)
http.Error(w, "rate limited", http.StatusTooManyRequests)
return
}
if r.reactionPublish == nil {
w.WriteHeader(http.StatusAccepted)
return
}
comment := e.GetComment()
reaction := workintake.ReviewCommentEnvelope{
Owner: e.GetRepo().GetOwner().GetLogin(),
Repo: e.GetRepo().GetName(),
PRNumber: e.GetPullRequest().GetNumber(),
Kind: workintake.ReviewReactionComment,
ReviewID: comment.GetPullRequestReviewID(),
CommentID: comment.GetID(),
Author: comment.GetUser().GetLogin(),
Body: comment.GetBody(),
Path: comment.GetPath(),
Line: comment.GetLine(),
}
r.deliverReaction(w, req, reaction)
}
func (r *Receiver) deliverReaction(w http.ResponseWriter, req *http.Request, reaction workintake.ReviewCommentEnvelope) {
if err := r.reactionPublish(req.Context(), reaction); err != nil {
r.log.Error("publish reaction", "key", reaction.IdempotencyKey(), "err", err)
http.Error(w, "publish failed", http.StatusInternalServerError)
return
}
r.recordReactionPublish()
w.WriteHeader(http.StatusAccepted)
}
// allowReactionDelivery consumes one reaction slot for the remote source.
// A fixed window keeps the bookkeeping trivial; the failure mode is a burst
// slightly over one window, which the consumer's dedup and round cap bound.
func (r *Receiver) allowReactionDelivery(remote string) bool {
now := time.Now()
r.mu.Lock()
defer r.mu.Unlock()
for k, v := range r.reactionLimiter {
if now.Sub(v.start) > reactionRateBucketTTL {
delete(r.reactionLimiter, k)
}
}
w, ok := r.reactionLimiter[remote]
if !ok || now.Sub(w.start) > reactionRateWindow {
r.reactionLimiter[remote] = &reactionWindow{start: now, count: 0}
w = r.reactionLimiter[remote]
}
w.count++
return w.count <= reactionRateLimit
}
// taskFromEvent decodes a GitHub issues event into a task envelope, or
// reports (zero, false) when the event is not eligible work.
func (r *Receiver) taskFromEvent(event *github.IssuesEvent) (workintake.TaskEnvelope, bool) {
Loaded 100 of 205 files, more files were not shown because too many files have changed in this diff. Show more