Merge branch 'crew/pi-1154'
This commit is contained in:
2 files changed
+98
No files matched your search
@@ -408,6 +408,12 @@
|
||||
"section": "PRDs",
|
||||
"body": "# Playbook data-flow and condition syntax\n\n**Status:** Approved\n**Date:** 2026-09-03\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-t2db.14` (expression environment).\n\n**Decision:** CEL via `cel.dev/cel-go` (v0.32.0), pinned. One expression\nmechanism covers both an action's `when` condition and its `args` values.\n\n## The requirement, stated directly\n\nA playbook action is gated and parametrised by runtime data: (a) a condition\ndeciding whether the action runs; (b) a later action's `args` values referencing\nan earlier action's `Result` and the triggering event's fields. Both are **CEL\nexpressions**, evaluated against one evaluation context. There is no separate\ninterpolation syntax: CEL reads nested maps and fields natively, so `args`\nvalues that need data are written as CEL, and only plain literal args remain\nplain YAML scalars.\n\nBoth halves are read-only: expressions may read context values and compute a\nresult from them, never mutate, never call host functions, never perform I/O.\nCEL enforces this structurally (no side effects, linear evaluation when macros\nare bounded, cost-limited).\n\n```yaml\nactions:\n - id: build\n position: module\n kind: log\n args:\n message: '\"build finished\"' # literal\n when: 'event.label == \"bugfix\"' # gate on event field\n - position: module\n kind: log\n args:\n message: '\"done: \" + string(actions.build.result.written)'\n when: \"actions.build.result.written == true\"\n```\n\n## Trust boundary of the expression\n\nA playbook YAML is **operator-installed, in-process, daemon-privileged** -- the\nsame tier as `ModuleDir`/`PluginDir`/`SecretEngineDir` (module-position.md's\ntrust-boundary section): loaded from a configured directory at startup, never\nfrom a webhook body or task worktree. The schema-by-example flow uses live\nevents to _design against_; the saved playbook is operator-authored file content\nin an operator-configured location.\n\nTwo consequences:\n\n1. The expression string is **trusted**. Operator-authored config, not attacker\n input; no sandboxing against a hostile expression string is required. If a\n future playbook source is less trusted (auto-generated bindings from\n unauthenticated captures), that is the playbook-file trust tier moving -- the\n loader's acceptance check is the right place, not the evaluator.\n2. The **data the expression reads is NOT trusted** (decoded webhook body, prior\n results through the same pipeline). Robustness against hostile data is\n required: no panic on wrong-typed/missing fields, no unbounded cost on\n deep/cyclic maps, bounded evaluation time. CEL provides this structurally\n (cost limits, linear non-Turing-complete evaluation, error values instead of\n panics -- verified in the vetting record below).\n\n## The gate precedent is deliberately NOT copied\n\n`internal/gate/gateeval` evaluates arbitrary interpreted Go (`.archie/gate.go`)\nas the repo's conditional-logic precedent. That is the wrong precedent for\nplaybook conditions because this document's premise is: **YAML is pure\norchestration data; Yaegi is where imperative logic lives** (Problem section;\nmodule-position.md's \"no generic hook\" section). Yaegi snippets in YAML would\nmove imperative logic into the data layer -- the inversion this design exists to\nprevent -- and make playbooks un-lintable.\n\nThe line: conditions are **declarative predicates over runtime data, not\nprograms**. CEL is non-Turing-complete and side-effect-free, so it cannot become\na program; a condition that needs real logic gets a Module kind (Yaegi),\nreferenced by the action, not a stronger expression body.\n\n## Plugin-engine-rule interaction\n\nThe plugin engine rule forbids a generic `Module` interface with an `any`\npayload; it exists to keep static implementation contracts typed. Evaluating CEL\nagainst runtime `map[string]any` is **not the same problem**: the rule concerns\n_implementation contracts_ (static operations a capability family exposes), not\n_runtime data values_ (legitimately dynamic -- an event payload's shape is\nunknown until it arrives). The Module contract stays fully typed (generated\n`Args`/`Result` schemas); CEL is a read-only data reader under the playbook\nengine family, not a new capability contract. Stated once.\n\n## Minimum viable evaluation context (what expressions see)\n\nOne flat context, namespaced from the playbook run, built at dispatch time:\n\n| Name | Type | Source |\n| --------- | ------------------------ | ---------------------------------------------------------------------------------Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/plugin-settings-live/",
|
||||
"title": "Plugin settings reconcile live",
|
||||
"section": "PRDs",
|
||||
"body": "# Plugin settings reconcile live\n\n**Status:** Draft\n**Tracking:** GitHub [#1154](https://github.com/samcharles93/archie-core/issues/1154), epic [#998](https://github.com/samcharles93/archie-core/issues/998)\n**Authority:** `docs/prds/runtime-control-plane.md` decides each feature owns how\nits changes take effect; `docs/architecture/plugins-and-extensions.md` owns the\nplugin engine rule; `docs/prds/control-plane-apply-status.md` owns where apply\nreports go.\n\n## Outcome\n\nAn operator drops a plugin, module or secret-engine file into the configured\ndirectory while archied runs, and the daemon loads it without a restart. An\nedit to an installed file replaces what is running. Deleting an installed file\nnever stops running code; apply status says so. A stored change to\n`plugin-settings` applies live for additions instead of requiring a restart.\n\n## Triggers\n\n`plugin-settings` joins the kinds archied watches (`PluginSettingsKind` moves\nto the live list in `internal/app/archied/control_plane.go`). After the daemon\nlayers a new version it reconciles the three directories the document names.\nA second trigger needs no document change: a poller reconciles on an interval,\nso a file dropped into a directory loads on its own. The poll interval is the\napply-status restamp constant; no filesystem-watch dependency is added. The\npoller reads the current document's directories from the running config each\ntick, so a changed `plugin_dir`, `module_dir` or `secret_engine_dir` retargets\nreconciliation without a restart.\n\n## Rules\n\n- Adding and changing load; removing never unloads. Yaegi interpreters are not\n reclaimed while a caller still exists and there is no unload path; the\n running set can only grow.\n- Each file is loaded through a fresh interpreter (the boot pattern). A changed\n file therefore loads cleanly, and replacement switches consumers to the new\n interpretation; files are content-hashed so only new and changed files load.\n- A file that fails to load is skipped and reported; already-running code keeps\n running. This is the degrade-and-skip convention `plugin.LoadDir` and\n `Registry.LoadDir` already apply at boot. Boot keeps its reject-at-load rule\n for the module directory; a broken file at runtime skips without aborting.\n- A directory that does not exist reconciles to an empty set.\n\n## The three registries\n\n- **Secret engines** (`internal/secret`). Reconciliation re-runs\n `Registry.LoadDir` against the live directory. `Register` replaces by name,\n so an edited engine takes effect for the next resolution. A deleted engine\n stays registered: existing references keep resolving through it until\n restart, and the record says so. Engines are stateless resolvers, so a swap\n needs no lifecycle step.\n- **Modules** (`internal/domain/eda/module`): reconciliation re-runs\n `ModuleRegistry.Register` for the kind's file. The invoker maps\n last-write-wins, and playbook dispatch resolves through the registry at\n invoke time, so the swap reaches a running playbook store unchanged. A file\n deleted for a kind leaves the old invoker in place, running; reported.\n- **Plugins** (`internal/plugin`): `Host` grows running-state operations beside\n `Register`, `Start` and `Stop`. One adds a single module while the host is\n running: it is inserted in dependency order, started alone, and on failure\n rolled back alone, leaving every previously started module running. The\n other replaces a module whose manifest id matches: stop it, start the new\n one, and restart the old one when the new start fails. Replacing a module\n that another depends on is refused, not swapped. These operations obey the\n plugin engine rule: the host still invokes start and stop itself, isolates\n the failure to the one module, and keeps a rollback. A deleted file makes no\n host call: the module runs on and is reported.\n\n## `skills_dir`\n\n`skills_dir` is not part of this change. The daemon refuses a candidate\n`plugin-settings` document whose `skills_dir` differs from the value it is\nrunning, reporting that the field applies on restart, until a skill\nreconciliation exists to carry it. The refusal is the existing rejected-edit\napply-status shape: the store keeps the version, the document is not applied,\nlast-known-good keeps running.\n\n## Apply status\n\nOne record: `archied` on `plugin-settings`. The reconciliation outcome is\nreported against the version the process is running. The record's error field\ncarries the outstanding reconciliation problem: a deleted file still running, a\nfile that failed to load, or the directory failing to read. A reconciliation\nwith nothing outstanding clears the error. The version stays the version the\nprocess is running; an add that succeeded is live even while a removal is\noutstanding, and the error says so rather than showing the kind as\nrestart-required. archie-gateway keeps boot-time loading; its record simply\nstays on the vLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/pr-review-agent/",
|
||||
"title": "PR review agent",
|
||||
@@ -851,6 +857,10 @@
|
||||
"title": "Playbook data-flow and condition syntax",
|
||||
"url": "/dev/prds/playbook-expression-syntax/"
|
||||
},
|
||||
{
|
||||
"title": "Plugin settings reconcile live",
|
||||
"url": "/dev/prds/plugin-settings-live/"
|
||||
},
|
||||
{
|
||||
"title": "PR review agent",
|
||||
"url": "/dev/prds/pr-review-agent/"
|
||||
|
||||
@@ -0,0 +1,88 @@
|
||||
# Plugin settings reconcile live
|
||||
|
||||
**Status:** Draft
|
||||
**Tracking:** GitHub [#1154](https://github.com/samcharles93/archie-core/issues/1154), epic [#998](https://github.com/samcharles93/archie-core/issues/998)
|
||||
**Authority:** `docs/prds/runtime-control-plane.md` decides each feature owns how
|
||||
its changes take effect; `docs/architecture/plugins-and-extensions.md` owns the
|
||||
plugin engine rule; `docs/prds/control-plane-apply-status.md` owns where apply
|
||||
reports go.
|
||||
|
||||
## Outcome
|
||||
|
||||
An operator drops a plugin, module or secret-engine file into the configured
|
||||
directory while archied runs, and the daemon loads it without a restart. An
|
||||
edit to an installed file replaces what is running. Deleting an installed file
|
||||
never stops running code; apply status says so. A stored change to
|
||||
`plugin-settings` applies live for additions instead of requiring a restart.
|
||||
|
||||
## Triggers
|
||||
|
||||
`plugin-settings` joins the kinds archied watches (`PluginSettingsKind` moves
|
||||
to the live list in `internal/app/archied/control_plane.go`). After the daemon
|
||||
layers a new version it reconciles the three directories the document names.
|
||||
A second trigger needs no document change: a poller reconciles on an interval,
|
||||
so a file dropped into a directory loads on its own. The poll interval is the
|
||||
apply-status restamp constant; no filesystem-watch dependency is added. The
|
||||
poller reads the current document's directories from the running config each
|
||||
tick, so a changed `plugin_dir`, `module_dir` or `secret_engine_dir` retargets
|
||||
reconciliation without a restart.
|
||||
|
||||
## Rules
|
||||
|
||||
- Adding and changing load; removing never unloads. Yaegi interpreters are not
|
||||
reclaimed while a caller still exists and there is no unload path; the
|
||||
running set can only grow.
|
||||
- Each file is loaded through a fresh interpreter (the boot pattern). A changed
|
||||
file therefore loads cleanly, and replacement switches consumers to the new
|
||||
interpretation; files are content-hashed so only new and changed files load.
|
||||
- A file that fails to load is skipped and reported; already-running code keeps
|
||||
running. This is the degrade-and-skip convention `plugin.LoadDir` and
|
||||
`Registry.LoadDir` already apply at boot. Boot keeps its reject-at-load rule
|
||||
for the module directory; a broken file at runtime skips without aborting.
|
||||
- A directory that does not exist reconciles to an empty set.
|
||||
|
||||
## The three registries
|
||||
|
||||
- **Secret engines** (`internal/secret`). Reconciliation re-runs
|
||||
`Registry.LoadDir` against the live directory. `Register` replaces by name,
|
||||
so an edited engine takes effect for the next resolution. A deleted engine
|
||||
stays registered: existing references keep resolving through it until
|
||||
restart, and the record says so. Engines are stateless resolvers, so a swap
|
||||
needs no lifecycle step.
|
||||
- **Modules** (`internal/domain/eda/module`): reconciliation re-runs
|
||||
`ModuleRegistry.Register` for the kind's file. The invoker maps
|
||||
last-write-wins, and playbook dispatch resolves through the registry at
|
||||
invoke time, so the swap reaches a running playbook store unchanged. A file
|
||||
deleted for a kind leaves the old invoker in place, running; reported.
|
||||
- **Plugins** (`internal/plugin`): `Host` grows running-state operations beside
|
||||
`Register`, `Start` and `Stop`. One adds a single module while the host is
|
||||
running: it is inserted in dependency order, started alone, and on failure
|
||||
rolled back alone, leaving every previously started module running. The
|
||||
other replaces a module whose manifest id matches: stop it, start the new
|
||||
one, and restart the old one when the new start fails. Replacing a module
|
||||
that another depends on is refused, not swapped. These operations obey the
|
||||
plugin engine rule: the host still invokes start and stop itself, isolates
|
||||
the failure to the one module, and keeps a rollback. A deleted file makes no
|
||||
host call: the module runs on and is reported.
|
||||
|
||||
## `skills_dir`
|
||||
|
||||
`skills_dir` is not part of this change. The daemon refuses a candidate
|
||||
`plugin-settings` document whose `skills_dir` differs from the value it is
|
||||
running, reporting that the field applies on restart, until a skill
|
||||
reconciliation exists to carry it. The refusal is the existing rejected-edit
|
||||
apply-status shape: the store keeps the version, the document is not applied,
|
||||
last-known-good keeps running.
|
||||
|
||||
## Apply status
|
||||
|
||||
One record: `archied` on `plugin-settings`. The reconciliation outcome is
|
||||
reported against the version the process is running. The record's error field
|
||||
carries the outstanding reconciliation problem: a deleted file still running, a
|
||||
file that failed to load, or the directory failing to read. A reconciliation
|
||||
with nothing outstanding clears the error. The version stays the version the
|
||||
process is running; an add that succeeded is live even while a removal is
|
||||
outstanding, and the error says so rather than showing the kind as
|
||||
restart-required. archie-gateway keeps boot-time loading; its record simply
|
||||
stays on the version it last applied until it restarts, which the per-process
|
||||
apply-status page already reads correctly.
|
||||
Reference in new issue
Block a user