tegwick
7d608c0d57
Some checks failed
Build and publish policy-nexus image / build-and-push (push) Failing after 55s
Harvest ops-warden's five ready records. Register ACT-ADR-001–005 after publication metadata landed in activity-core. Markitect arc42-v1 and the estate infospace are now the validation and retrieval path.
247 lines
25 KiB
HTML
247 lines
25 KiB
HTML
<!doctype html>
|
|
<html lang="en"><meta charset="utf-8">
|
|
<meta name="policy-source-revision" content="41a3fb8b81bd521a5fa21af114975c54532df3ad">
|
|
<meta name="policy-source-digest" content="ac70015255b8972c7ee38f1a0fb934c6aa5f397634ddc298f0878a8eed6a774a">
|
|
<title>Activity-Core as Coulomb Org Event Bridge</title>
|
|
<style>
|
|
:root{
|
|
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
|
|
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
|
|
--rule:#D3D7DC; --rule-strong:#B6BCC3;
|
|
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
|
|
--clay:#8A3A2C; --clay-soft:#F2DFDA;
|
|
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
|
|
--chip-fg:#F6F7F8;
|
|
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
|
|
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
|
|
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
|
|
--measure:66ch;
|
|
}
|
|
@media (prefers-color-scheme:dark){
|
|
:root:not([data-theme="light"]){
|
|
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
|
|
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
|
|
--rule:#2A3138; --rule-strong:#3B444D;
|
|
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
|
|
--clay:#D08A76; --clay-soft:#3A211B;
|
|
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
|
|
--chip-fg:#12161A;
|
|
}
|
|
}
|
|
:root[data-theme="dark"]{
|
|
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
|
|
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
|
|
--rule:#2A3138; --rule-strong:#3B444D;
|
|
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
|
|
--clay:#D08A76; --clay-soft:#3A211B;
|
|
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
|
|
--chip-fg:#12161A;
|
|
}
|
|
|
|
*{box-sizing:border-box}
|
|
body{
|
|
margin:0; background:var(--paper); color:var(--ink);
|
|
font-family:var(--font-body); font-size:17px; line-height:1.62;
|
|
-webkit-font-smoothing:antialiased;
|
|
}
|
|
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
|
|
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
|
|
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
|
|
|
|
/* ---------- rail ---------- */
|
|
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
|
|
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
|
|
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
|
|
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
|
|
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
|
|
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
|
|
|
|
/* ---------- header ---------- */
|
|
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
|
|
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
|
|
.eyebrow .stat{color:var(--clay)}
|
|
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
|
|
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
|
|
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
|
|
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
|
|
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
|
|
|
|
/* ---------- typography ---------- */
|
|
section{margin-bottom:60px;scroll-margin-top:24px}
|
|
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
|
|
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
|
|
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
|
|
p{margin:0 0 15px;max-width:var(--measure)}
|
|
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
|
|
li{margin-bottom:7px}
|
|
strong{font-weight:600}
|
|
em{font-style:italic}
|
|
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
|
|
a{color:var(--brass)}
|
|
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
|
|
|
|
/* ---------- devices ---------- */
|
|
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
|
|
.callout p:last-child{margin-bottom:0}
|
|
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
|
|
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
|
|
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
|
|
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
|
|
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
|
|
.hard p:last-child{margin-bottom:0}
|
|
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
|
|
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
|
|
|
|
/* ---------- tables ---------- */
|
|
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
|
|
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
|
|
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
|
|
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
|
|
td:first-child{color:var(--ink);font-weight:600}
|
|
tbody tr:last-child td{border-bottom:none}
|
|
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
|
|
|
|
/* ---------- ladders ---------- */
|
|
.breakout{margin:34px 0 40px}
|
|
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
|
|
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
|
|
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
|
|
.ladders{display:grid;gap:26px}
|
|
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
|
|
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
|
|
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
|
|
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
|
|
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
|
|
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
|
|
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
|
|
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
|
|
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
|
|
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
|
|
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
|
|
.rung.na{opacity:.42}
|
|
|
|
/* ---------- matrix ---------- */
|
|
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
|
|
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
|
|
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
|
|
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
|
|
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
|
|
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
|
|
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
|
|
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
|
|
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
|
|
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
|
|
.rlab{min-height:60px}
|
|
.clab{padding-top:7px;min-height:22px}
|
|
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
|
|
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
|
|
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
|
|
.mnote .k{display:flex;align-items:center;gap:7px}
|
|
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
|
|
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
|
|
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
|
|
@media (max-width:640px){
|
|
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
|
|
.mcell{min-height:52px;padding:4px}
|
|
.pin{font-size:8px;padding:1px 3px}
|
|
.rlab{min-height:52px}
|
|
}
|
|
|
|
/* ---------- methodology ---------- */
|
|
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
|
|
.verb{background:var(--surface);padding:18px 18px 20px}
|
|
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
|
|
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
|
|
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
|
|
|
|
/* ---------- questions ---------- */
|
|
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
|
|
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
|
|
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
|
|
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
|
|
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
|
|
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
|
|
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
|
|
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
|
|
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
|
|
|
|
/* ---------- misc ---------- */
|
|
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
|
|
.numbers .v{color:var(--ink);font-weight:600}
|
|
.numbers .k{color:var(--ink-3)}
|
|
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
|
|
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
|
|
.alt:last-of-type{border-bottom:none}
|
|
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
|
|
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
|
|
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
|
|
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
|
|
.tm td,.tm th{text-align:center}
|
|
.tm td:first-child,.tm th:first-child{text-align:left}
|
|
.yes{color:var(--l4);font-weight:700}
|
|
.no{color:var(--clay);font-weight:700}
|
|
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
|
|
.kind.adv{border-color:var(--clay);color:var(--clay)}
|
|
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
|
|
.route{background:var(--surface);padding:16px 18px}
|
|
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
|
|
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
|
|
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
|
|
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
|
|
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
|
|
|
|
</style>
|
|
<div class="wrap"><header><div class="eyebrow"><span>ACT-ADR-001</span> <span class="stat">accepted · accepted-1</span> <span>activity-core</span> <span>reviewed 2026-05-14</span><span>generated from canonical source — do not edit</span></div><h1>Activity-Core as Coulomb Org Event Bridge</h1><p class="sub">Source: <code>activity-core · docs/adr/adr-001-event-bridge-architecture.md · 41a3fb8b81bd521a5fa21af114975c54532df3ad</code></p><p class="sub">Review due: 2026-11-14</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#trigger-types"><span class="n">·</span>Trigger types</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#alternatives-considered"><span class="n">·</span>Alternatives Considered</a></li><li><a href="#related"><span class="n">·</span>Related</a></li></ol></nav><main><section id="status"><h2>Status</h2>
|
|
<p>Accepted.</p>
|
|
</section>
|
|
<section id="context"><h2>Context</h2>
|
|
<p>The Coulomb organization's set of repositories, services, and deployments is growing beyond what a single person can coordinate manually. The state hub tracks cross-domain state but has no mechanism to automatically respond to it. Recurring maintenance (dependency scans, SBOM staleness checks, consistency audits) is implemented as bespoke cron jobs baked into individual services — scattered, hard to audit, and impossible to govern from a single vantage point.</p>
|
|
<p>Three forces drive the need for a dedicated orchestration layer:</p>
|
|
<ol><li><strong>Scale</strong>: as the repo count grows, manual coordination becomes the bottleneck.</li><li><strong>Reactivity</strong>: org-level events (new repo registered, CVE published, deployment completed) should trigger coordinated responses without human intervention.</li><li><strong>Separation of concerns</strong>: the state hub is a read model and should remain one. It must not accumulate automation logic to avoid becoming a God object.</li></ol>
|
|
</section>
|
|
<section id="decision"><h2>Decision</h2>
|
|
<p><strong>activity-core is the org-wide Event Bridge for the Coulomb organization.</strong></p>
|
|
<p>Its responsibility is exactly three things:</p>
|
|
<ol><li><strong>Receive events</strong> — time-based (cron, one-off scheduled) and domain events (NATS, Gitea webhooks, state hub lifecycle signals).</li><li><strong>Evaluate rules and instructions</strong> — given event payload and resolved context, determine what work must be created.</li><li><strong>Emit task sets</strong> — publish structured task creation requests to issue-core.</li></ol>
|
|
<p>It does not execute work. It does not track task lifecycle. It does not manage projects.</p>
|
|
<h3>Boundary rules</h3>
|
|
<div class="scroll"><table><thead><tr><th>Concern</th><th>Owner</th></tr></thead><tbody><tr><td>Cross-org task scheduling and reactive automation</td><td><strong>activity-core</strong></td></tr><tr><td>Task lifecycle (create, assign, track, close)</td><td><strong>issue-core</strong></td></tr><tr><td>Project and initiative management (phased, completion-gated)</td><td><strong>project-core</strong> (future)</td></tr><tr><td>Repository capability profiling</td><td><strong>repo-scoping</strong></td></tr><tr><td>Cross-domain coordination state</td><td><strong>state hub</strong></td></tr><tr><td>Execution of automatable tasks</td><td>Temporal workers (per-repo)</td></tr></tbody></table></div>
|
|
<h3>Event type registry</h3>
|
|
<p>Event types are declared by publishers as markdown definition files (see ACT-ADR-002). Governance is <strong>publisher-declared by default</strong>: a publisher registers its event types by committing definition files to the event-types registry. In production environments, a curator gate can be enabled — registry entries must be reviewed before the runtime accepts events of that type. This is a configuration flag per runtime scope (dev, staging, prod), not a hard-coded rule.</p>
|
|
<h3>State hub relationship</h3>
|
|
<p>The state hub <strong>delegates automation to activity-core</strong> rather than implementing it internally. Concretely:</p>
|
|
<ul><li>Maintenance jobs currently baked into the state hub (consistency sync, SBOM staleness checks) are migrated to ActivityDefinitions in activity-core.</li><li>The state hub becomes a <strong>publisher</strong> of lifecycle events on NATS (<code>org.workstream.created</code>, <code>org.decision.resolved</code>, <code>org.repo.registered</code>, etc.).</li><li>The state hub does not subscribe to activity-core's output directly; it reads task state from issue-core when needed.</li></ul>
|
|
<p>This preserves the state hub as a read model and makes activity-core the single home for automation policy.</p>
|
|
<h3>rules-core: module-first</h3>
|
|
<p>The rule and instruction evaluation engine starts as <code>src/activity_core/rules/</code> — a module with a clean internal boundary (no imports from Temporal, Postgres, or FastAPI within the module). Extraction to a standalone <code>rules-core</code> repository happens when a <strong>second consumer</strong> (e.g. state hub governance, project-core) needs the engine. This follows the same discipline as the task-flow-engine extraction plan (CUST-TFE-SCOPE).</p>
|
|
<h3>NATS as org infrastructure</h3>
|
|
<p>NATS JetStream is promoted from an activity-core internal component to <strong>org-wide event bus infrastructure</strong>. It runs as a standalone service (not bundled in activity-core's docker-compose) with its own lifecycle. All services that publish or subscribe to org events do so via NATS streams.</p>
|
|
<h3>issue-core integration</h3>
|
|
<p>activity-core communicates with issue-core via a <strong>task emission adapter</strong> — an abstraction layer that, in the initial implementation, calls issue-core's REST API. The adapter interface is defined now; the transport can migrate to NATS subscription (issue-core subscribes to <code>task.spawned</code> events) once issue-core adds that capability. This avoids hardcoding REST coupling throughout the codebase.</p>
|
|
<h3>Webhook receiver</h3>
|
|
<p>A new HTTP endpoint within activity-core accepts inbound webhooks from Gitea (and later GitHub, other services). It normalises payloads to the canonical EventEnvelope format, validates against the event type registry, and publishes to NATS. This runs alongside the existing FastAPI <code>api.py</code>.</p>
|
|
<h3>Domain assignment</h3>
|
|
<p>activity-core and issue-core are assigned to the <strong><code>capabilities</code></strong> domain — the same domain as repo-scoping. These are org-wide infrastructure tools that serve all domains equally, not artefacts of any single project or custodian's personal workflow. issue-core is explicitly disassociated from the markitect domain.</p>
|
|
</section>
|
|
<section id="trigger-types"><h2>Trigger types</h2>
|
|
<p>Three trigger types are supported:</p>
|
|
<div class="scroll"><table><thead><tr><th>Type</th><th>Description</th><th>Temporal mechanism</th></tr></thead><tbody><tr><td><code>cron</code></td><td>Recurring schedule (5-field cron + timezone + misfire policy)</td><td>Temporal Schedule (implemented WP-0002)</td></tr><tr><td><code>event</code></td><td>React to a named event type on NATS</td><td>Temporal workflow started by Event Router</td></tr><tr><td><code>scheduled</code></td><td>One-off at a future datetime</td><td>Temporal Schedule with <code>remaining_actions: 1</code></td></tr></tbody></table></div>
|
|
<p><code>scheduled</code> is a new trigger type added in WP-0003.</p>
|
|
</section>
|
|
<section id="consequences"><h2>Consequences</h2>
|
|
<h3>Immediate</h3>
|
|
<ul><li>activity-core's <code>INTENT.md</code> and <code>SCOPE.md</code> are rewritten to reflect this architecture.</li><li>The <code>task_instances</code> Postgres table is reclassified as a <strong>spawn audit trail</strong> — it records the act of spawning (what was created, when, which issue-core reference) but is not the authoritative task record. Authoritative lifecycle state lives in issue-core.</li><li>A task emission adapter interface (<code>src/activity_core/issue_sink.py</code>) replaces any direct Postgres writes to <code>task_instances</code> with calls through the adapter.</li><li>The <code>TaskExecutorWorkflow</code> stub from WP-0001 is replaced with the actual adapter call in WP-0003.</li></ul>
|
|
<h3>Medium term</h3>
|
|
<ul><li>State hub adds NATS publishing to its lifecycle operations.</li><li>Gitea webhook receiver added to activity-core as a new HTTP router.</li><li>Existing state hub maintenance crons are migrated to ActivityDefinitions.</li><li>issue-facade is renamed issue-core and re-registered under the <code>capabilities</code> domain.</li></ul>
|
|
<h3>Long term</h3>
|
|
<ul><li>rules-core extracted as a standalone package when a second consumer appears.</li><li>project-core created (depends on task-flow-engine extraction) for multi-phase initiative management — explicitly out of scope for activity-core.</li><li>NATS gets its own operational runbook and monitoring as org infrastructure.</li></ul>
|
|
</section>
|
|
<section id="alternatives-considered"><h2>Alternatives Considered</h2>
|
|
<p><strong>State hub absorbs activity-core functionality</strong>: rejected — turns the state hub into a God object, violates the read-model boundary, and makes automation logic impossible to test independently.</p>
|
|
<p><strong>Per-repo automation (GitHub Actions style)</strong>: rejected — cross-repo coordination requires a single vantage point that can see all repos; per-repo actions can't express org-level triggers or context.</p>
|
|
<p><strong>Activity-core as a thin Temporal wrapper only</strong>: rejected — without the event type registry and rule model, it's just a scheduler. The governance and introspection properties are the point.</p>
|
|
<p><strong>Separate rules-core from day one</strong>: rejected — premature extraction adds dependency management overhead before a second consumer exists. Module-first with a clean boundary costs nothing and preserves the extraction option.</p>
|
|
</section>
|
|
<section id="related"><h2>Related</h2>
|
|
<ul><li>ACT-ADR-002 — Event type and ActivityDefinition definition format</li><li>ACT-ADR-003 — Rule vs. Instruction model and DSL</li><li>CUST-ADR-001 — Workplans as repository artefacts (canon/architecture/)</li><li>CUST-TFE-SCOPE-2026-000001 — task-flow-engine extraction plan (canon/projects/)</li><li>activity-core INTENT.md (to be written)</li><li>activity-core WP-0003 (to be written)</li></ul>
|
|
</section><footer><span>ACT-ADR-001 · accepted-1 · accepted</span><span>activity-core · docs/adr/adr-001-event-bridge-architecture.md · 41a3fb8b81bd521a5fa21af114975c54532df3ad</span></footer></main></div></div></html>
|