feat(bus): approve and activate an exact product PRD version (#1839)

This commit is contained in:
jason.woltje committed 2026-11-04 10:49:15 -06:00
1 parent ea0e885bc9
commit c098fa022c
31 files changed
+840 -61

No files matched your search

+77 -7
View File
@@ -123,6 +123,10 @@ export const HOST_STDIN_MAX = 65536;
export const HOST_TIMEOUT_DEFAULT = 60;
export const HOST_TIMEOUT_MAX = 900;
const sha256 = (x) => createHash('sha256').update(x).digest('hex');
// Canonical candidate bindings remain pure so the broker's sandbox import closure stays fixed.
const orderedPrd = value => Array.isArray(value) ? value.map(orderedPrd) : object(value)
? Object.fromEntries(Object.keys(value).sort().map(k => [k, orderedPrd(value[k])])) : value;
const digestPrd = value => sha256(JSON.stringify(orderedPrd(value)));
// D4: what a host.sudo decision binds, from the raise's args and again from the call's.
const hostRun = (host, argv, stdin) => ({
host,
@@ -156,7 +160,7 @@ export const USER_VERBS = Object.freeze(['project.list', 'thread.create', 'threa
'thread.share', 'thread.unshare', 'thread.shares']);
// Row 252 (#1753, design sections 2-3): the only verbs a Console owner cap reaches. Every other verb
// refuses it human-required before its own checks, and these refuse every other cap.
export const CONSOLE_VERBS = Object.freeze(['decision.preview.console', 'decision.resolve.console']);
export const CONSOLE_VERBS = Object.freeze(['decision.preview.console', 'decision.resolve.console', 'prd.revoke.console', 'request.mode.console', 'request.draft.console']);
// Row 275 (193b1b, #1780, row 193 design 4.3 and 9): the user verbs a viewer grant reaches. They
// read, so a live grant at any level covers them. thread.create, thread.open and thread.send need a
// collaborator grant on the project and instance, so a viewer gets access-refused on each.
@@ -593,6 +597,12 @@ export class Broker {
},
projectPaths: business => Object.values(this.#business(business).projects ?? {}).flatMap(p => [p.root, p.repo]).filter(p => typeof p === 'string'),
raiseDecision: (identity, args) => this.#dispatch(identity, 'decision.raise', args),
raisePrdDecision: (identity, args, spec) => this.#dispatch(identity, 'decision.raise', args, spec),
prdBusiness: business => structuredClone(this.#business(business)),
prdAuthority: (state, binding) => this.#prdAuthority(state, binding),
prdApproval: (state, binding) => this.#prdApproval(state, binding),
prdDecision: (business, decision) => this.#decisionView(this.#store.get('SELECT * FROM decisions WHERE business=? AND id=?', business, decision)),
recordPrd: (identity, project, decision) => this.#consumeAuthority(identity, 'record.write', { target: project }, { operation: 'prd.submit', decision }),
readDecision: (business, decision) => {
const d = this.#store.get('SELECT * FROM decisions WHERE business=? AND id=?', business, decision);
if (!d || d.action !== 'project.bootstrap' || d.route_to !== 'human') fail('request-selection-refused');
@@ -613,18 +623,68 @@ export class Broker {
if (!s || s.business !== state.business) fail('request-access-refused');
if (s.reader) fail('read-only');
if (s.tester) fail('tester-refused');
if (s.user || s.console) fail('human-required');
if (s.user || (s.console && !['mode','draft'].includes(operation))) fail('human-required');
if (['mode','draft'].includes(operation) && !s.console) fail('human-required');
if (s.human) {
this.#human(s);
if (!s.console) this.#human(s);
if (s.human !== state.owner || s.human !== this.#business(s.business).human) fail('request-access-refused');
if (operation === 'propose') fail('agent-required');
if (['propose','prd.submit'].includes(operation)) fail('agent-required');
} else {
this.#agent(s);
if (s.role !== state.pm || this.#business(s.business).roles[s.role]?.definition !== 'pm') fail('request-access-refused');
// No separate authority: intake preparation consumes the PM's existing message.send grant.
if (operation !== 'get') this.#checkAuthority(s, 'message.send', { target: state.pm });
if (operation === 'prd.submit') this.#checkAuthority(s, 'record.write', { target: state.project });
else if (operation !== 'get') this.#checkAuthority(s, 'message.send', { target: state.pm });
}
}
#prdAuthority(state, binding) {
if (!state || !binding) fail('prd-authority-refused');
const b = this.#business(state.business), pm = b.roles[state.pm];
if (b.human !== state.owner || pm?.definition !== 'pm' || !pm.authority?.withinRole.includes('record.write')) fail('prd-authority-refused');
for (const author of binding.authors ?? []) {
const r = b.roles[author.instance];
if (r?.definition !== author.definition || !r.authority?.withinRole.includes('record.write')) fail('prd-authority-refused');
}
let route = { instance: 'human', definition: 'human' };
if (state.mode === 'autonomous') {
const instance = b.arbiters?.technical, arbiter = b.roles[instance];
if (!instance || !arbiter || !arbiter.authority?.withinRole.includes('decision.resolve.technical')) fail('prd-arbiter-unavailable');
if (instance === state.pm || arbiter.definition === pm.definition || binding.authors?.some(a => a.instance === instance || a.definition === arbiter.definition)) fail('prd-self-approval');
route = { instance, definition: arbiter.definition };
}
if (binding.route && digestPrd(binding.route) !== digestPrd(route)) fail('prd-authority-refused');
return route;
}
#prdApproval(state, binding) {
const route = this.#prdAuthority(state, binding), d = this.#store.get('SELECT * FROM decisions WHERE business=? AND id=?', state.business, binding.decision);
const r = d && this.#closed(d.id), raised = d && this.#raised(state.business, d.id);
if (!d || d.action !== 'prd.approve' || d.project !== state.project || d.raised_by_role !== state.pm || d.route_to !== route.instance ||
d.blocking !== 0 || d.task_ref !== null || d.requirement_ref !== null || d.class !== 'gated' ||
raised?.target !== `prd-${digestPrd(binding.candidate)}` || raised?.approvalChoice !== 'yes' ||
(state.mode === 'autonomous' ? d.spec_commit !== binding.candidate.spec_commit || d.spec_path !== SPEC_PATH : d.spec_commit !== null)) fail('prd-authority-refused');
if (!r) fail('prd-not-approved');
if (r.op !== 'resolved') fail('prd-decision-closed');
if (r.choice !== raised.approvalChoice) fail('prd-changes-requested');
if (route.instance === 'human') {
if (r.by !== state.owner || !['cli','console'].includes(r.via) || (r.via === 'console' && !this.#consoleInput(state.business, d.id, r))) fail('prd-authority-refused');
} else if (r.via !== 'broker' || !(this.#store.get("SELECT 1 FROM role_claims WHERE business=? AND role=? AND holder_run=? AND op='claim'", state.business, route.instance, r.by) ||
this.#store.get("SELECT 1 FROM thread_claims c JOIN threads t ON t.id=c.thread WHERE c.business=? AND t.instance=? AND c.holder_run=? AND c.op='claim'", state.business, route.instance, r.by))) fail('prd-authority-refused');
return { decision: d.id, resolution_seq: r.seq, by: r.by, via: r.via };
}
async requirementsFor(cap, args) {
const s = this.#session(cap);
try {
keys(args, ['project_key','requirement_snapshot','requirement'], ['project_key']);
this.#agent(s); this.#processingGate(s, 'requirements');
if (!this.#business(s.business).projects?.[args.project_key]) fail('request-project-refused');
if (!this.#requests?.catalog) fail('requirement-snapshot-required');
const result = await this.#requests.catalog.resolve({ business: s.business, project: args.project_key,
...(args.requirement_snapshot === undefined ? {} : { snapshot: args.requirement_snapshot }) });
this.#agent(s); this.#processingGate(s, 'requirements');
if (args.requirement !== undefined && !result.requirements.some(r => r.id === args.requirement)) fail('unknown-requirement');
return result;
} catch (e) { throw this.#refused(s, new BusError(e.code ?? 'requirement-snapshot-refused'), { args }); }
}
#requestOrigin(s, request) {
const b = this.#business(s.business);
const e = this.#store.get("SELECT * FROM events WHERE business=? AND id=? AND kind='human.input' AND actor_role IS NULL AND actor_run IS NULL", s.business, request);
@@ -5070,11 +5130,18 @@ export class Broker {
return { ended: ended.map((h) => ({ thread: h.thread, session: h.session, run: h.holder_run })) };
}
this.#processingGate(s, request.verb);
if (['request.open','request.get','request.projects','request.propose'].includes(request.verb)) {
if (['prd.revoke.console','request.mode.console','request.draft.console'].includes(request.verb)) {
if (!s.console || s.human !== this.#business(s.business).human) fail('human-required');
if (!this.#requests?.catalog) fail('request-not-configured');
return Promise.resolve().then(() => request.verb === 'request.draft.console' ? this.#requests.draftConsole(s, structuredClone(args)) : request.verb === 'prd.revoke.console'
? this.#requests.catalog.revoke(s, structuredClone(args)) : this.#requests.modeConsole(s, structuredClone(args)))
.catch(e => { throw this.#refused(s, new BusError(e.code ?? 'request-failed'), request); });
}
if (['request.open','request.get','request.projects','request.propose','prd.submit'].includes(request.verb)) {
if (s.reader) fail('read-only');
if (s.tester) fail('tester-refused');
if (!this.#requests) fail('request-not-configured');
const method = request.verb.slice('request.'.length);
const method = request.verb === 'prd.submit' ? 'submit' : request.verb.slice('request.'.length);
return Promise.resolve().then(() => this.#requests[method](s, structuredClone(args)))
.then(result => { this.#secretCheck(result); return result; })
.catch(e => { throw this.#refused(s, e instanceof BusError ? e : new BusError(e.code ?? 'request-failed'), request); });
@@ -6387,6 +6454,8 @@ export class Broker {
);
this.#route(s.business, mid, d.raised_by_role, session);
}
if (op !== 'seen' && d.action === 'prd.approve' && this.#requests)
setImmediate(() => { Promise.resolve().then(() => this.#requests.decisionClosed?.(s.business, d.id)).catch(() => {}); });
const answer = viaConsole ? { id: d.id, op, choice: a.choice } : { id: d.id, op };
return grant ? { ...answer, grant: 'started' } : answer;
}
@@ -7573,6 +7642,7 @@ export class Broker {
// The notice sits in no thread, so the user's thread view shows none of this traffic. Nothing is
// launched here: a notice to a role no run holds waits for a claim and does not tell launch.by.
#specNotice(business, project, commit, base) {
this.#requests?.catalog?.invalidate(business, project, 'requirement-snapshot-revoked', true);
const b = this.#business(business);
const roles = Object.keys(b.roles).filter((r) => SPEC_REVIEWERS.includes(b.roles[r].definition));
if (!roles.length) return;
+45
View File
@@ -0,0 +1,45 @@
-- Task 4: preserve all evidence and guards, widen only lifecycle event kinds.
DROP TRIGGER request_events_origin;
DROP TRIGGER request_events_revision;
DROP TRIGGER request_effects_binding;
DROP TRIGGER request_events_no_update;
DROP TRIGGER request_events_no_delete;
DROP TRIGGER request_events_no_replace;
DROP INDEX request_events_request;
ALTER TABLE request_events RENAME TO request_events_3p;
CREATE TABLE request_events (
seq INTEGER PRIMARY KEY AUTOINCREMENT,
business TEXT NOT NULL,
request TEXT NOT NULL REFERENCES events(id),
revision INTEGER NOT NULL CHECK (revision >= 1),
kind TEXT NOT NULL CHECK (kind IN ('opened','selection.proposed','selection.staged','selection.confirmed','setup.wait','bootstrap.stale','bootstrap.completed','prd.submitted','prd.activated','prd.invalidated','mode.changed','cancelled')),
actor_role TEXT, actor_run TEXT,
at TEXT NOT NULL,
body TEXT NOT NULL CHECK (json_valid(body) AND json_type(body) = 'object'),
CHECK ((actor_role IS NULL) = (actor_run IS NULL)),
UNIQUE (business,request,revision)
) STRICT;
INSERT INTO request_events(seq,business,request,revision,kind,actor_role,actor_run,at,body)
SELECT seq,business,request,revision,kind,actor_role,actor_run,at,body FROM request_events_3p ORDER BY seq;
DELETE FROM sqlite_sequence WHERE name='request_events';
INSERT INTO sqlite_sequence(name,seq) SELECT 'request_events', seq FROM sqlite_sequence WHERE name='request_events_3p';
DROP TABLE request_events_3p;
CREATE INDEX request_events_request ON request_events (business,request,seq);
CREATE TRIGGER request_events_origin BEFORE INSERT ON request_events
WHEN NOT EXISTS (SELECT 1 FROM events e JOIN messages m ON m.id=e.subject AND m.id=json_extract(e.body,'$.message')
WHERE e.id=NEW.request AND e.business=NEW.business AND m.business=e.business AND e.kind='human.input'
AND e.actor_role IS NULL AND e.actor_run IS NULL AND json_extract(e.body,'$.kind')='instruction' AND m.from_role='human')
BEGIN SELECT RAISE(ABORT, 'request-origin-refused'); END;
CREATE TRIGGER request_events_revision BEFORE INSERT ON request_events
WHEN NEW.revision <> 1 + coalesce((SELECT max(revision) FROM request_events WHERE business=NEW.business AND request=NEW.request),0)
OR (NEW.revision=1) <> (NEW.kind='opened')
BEGIN SELECT RAISE(ABORT, 'request-revision-conflict'); END;
CREATE TRIGGER request_effects_binding BEFORE INSERT ON request_effects
WHEN NOT EXISTS (SELECT 1 FROM request_events WHERE business=NEW.business AND request=NEW.request)
OR EXISTS (SELECT 1 FROM request_effects WHERE business=NEW.business AND request=NEW.request AND op=NEW.op AND (digest<>NEW.digest OR kind<>NEW.kind))
OR (NEW.stage<>'prepared' AND NOT EXISTS (SELECT 1 FROM request_effects WHERE business=NEW.business AND request=NEW.request AND op=NEW.op AND stage='prepared'))
OR EXISTS (SELECT 1 FROM request_effects WHERE business=NEW.business AND request=NEW.request AND op=NEW.op AND stage IN ('committed','refused'))
BEGIN SELECT RAISE(ABORT, 'request-effect-conflict'); END;
CREATE TRIGGER request_events_no_update BEFORE UPDATE ON request_events BEGIN SELECT RAISE(ABORT, 'request_events is append-only'); END;
CREATE TRIGGER request_events_no_delete BEFORE DELETE ON request_events BEGIN SELECT RAISE(ABORT, 'request_events is append-only'); END;
CREATE TRIGGER request_events_no_replace BEFORE INSERT ON request_events WHEN EXISTS (SELECT 1 FROM request_events WHERE seq=NEW.seq OR (business=NEW.business AND request=NEW.request AND revision=NEW.revision)) BEGIN SELECT RAISE(ABORT, 'request_events is append-only'); END;
+87 -1
View File
@@ -6,6 +6,7 @@ import { exact, object, id, key, text, digest, validatePlan, refuse } from './re
export function createRequestLifecycle({ journal, services }) {
if (!journal || !services || !['origin','authorize','raiseDecision','readDecision','project'].every(k => typeof services[k] === 'function')) refuse('request-services-unavailable');
let closing = false;
const pending = new Map();
const serial = (business, request, fn) => {
const k = business + '/' + request;
@@ -200,9 +201,79 @@ export function createRequestLifecycle({ journal, services }) {
return append(state, 'bootstrap.completed', { digest: binding.digest, project: done.project, chat_project: done.chat_project,
spec_commit: done.spec_commit, organization_revision: done.organization_revision });
}
async function submit(identity, args) {
exact(args, ['request','revision','op','prd_version','records_commit','prd_path','requirement_ids']);
if (!id(args.request) || !id(args.op) || !Number.isSafeInteger(args.revision) || args.revision < 1) refuse('invalid-request');
return serial(identity.business, args.request, async () => {
let state = stateOf(identity.business, args.request); authorize(identity, state, 'prd.submit');
const proposal_digest = digest(args), old = journal.proposal(state.business, state.request, args.op);
if (old) {
if (old.proposal_digest !== proposal_digest) refuse('request-operation-conflict');
if (!old.candidate) return state;
return { candidate: old.candidate, decision: services.prdDecision(state.business, old.decision) };
}
if (state.revision !== args.revision) refuse('request-revision-conflict');
if (!['discovery','prd-review','planning'].includes(state.phase) || state.wait?.code === 'prd-approval') refuse('request-phase-refused');
const { revision, op, ...input } = args;
const material = await services.readCandidate({ ...input, project: state.project, mode_revision: state.mode_revision }, state.business);
const recheck = () => {
const now = stateOf(state.business, state.request); authorize(identity, now, 'prd.submit');
if (now.revision !== args.revision) refuse('request-revision-conflict');
if (journal.projectState(state.business, state.project)?.revision !== state.mode_revision) refuse('prd-admission-revoked');
return now;
};
return journal.transaction(tx => {
state = recheck();
let route;
try { route = services.prdAuthority(state, { authors: material.authors }); }
catch (e) { if (!['prd-arbiter-unavailable','prd-self-approval'].includes(e.code)) throw e; return wait(state, e.code, identity, {}, tx.appendRequest); }
const candidate = material.candidate;
const decision = services.raisePrdDecision(identity, { action: 'prd.approve', domain: 'technical', project: state.project,
target: `prd-${digest(candidate)}`, question: `Approve product PRD ${candidate.prd_version} for ${state.project}, exact candidate ${digest(candidate)} at ${candidate.records_commit}?`,
options: [{ key: 'yes', text: 'Approve this exact product PRD version' }, { key: 'no', text: 'Request changes' }], recommendation: 'yes', approvalChoice: 'yes', blocking: false,
...(state.mode === 'autonomous' ? { spec_path: 'spec/north-star.md', spec_commit: candidate.spec_commit } : {}) },
state.mode === 'autonomous' ? { path: 'spec/north-star.md', commit: candidate.spec_commit } : null);
const header = { version: 1, business: state.business, request: state.request, op, kind: 'prd-submit', digest: proposal_digest };
journal.prepareEffect({ ...header, stage: 'prepared', result: null, code: null });
// A replacement retires existing admissions without changing their immutable evidence.
if (state.snapshot) services.catalog.invalidate(state.business, state.project, 'prd-replaced');
state = stateOf(state.business, state.request);
append(state, 'prd.submitted', { candidate, decision: decision.id, op, proposal_digest, authors: material.authors, route }, identity, tx.appendRequest);
journal.finishEffect({ ...header, stage: 'committed', result: { decision: decision.id }, code: null });
services.recordPrd?.(identity, state.project, decision.id);
return { candidate, decision };
});
});
}
async function modeConsole(identity, args) {
exact(args, ['request','revision','mode_revision','mode','op']);
if (!id(args.request) || !id(args.op) || !Number.isSafeInteger(args.revision) || !Number.isSafeInteger(args.mode_revision) || !['guided','autonomous'].includes(args.mode)) refuse('invalid-request');
return serial(identity.business, args.request, () => journal.transaction(() => {
let state = stateOf(identity.business, args.request); authorize(identity, state, 'mode');
const proposal_digest = digest(args), old = journal.proposal(state.business, state.request, args.op);
if (old) { if (old.proposal_digest !== proposal_digest) refuse('request-operation-conflict'); return state; }
if (state.revision !== args.revision) refuse('request-revision-conflict');
if (!state.project || args.mode_revision !== state.mode_revision) refuse('request-mode-revision-conflict');
const mode_revision = journal.changeMode({ business: state.business, project: state.project, revision: args.mode_revision, mode: args.mode, op: args.op, request: args.request });
services.catalog.invalidate(state.business, state.project, 'request-mode-changed');
for (const row of journal.listRequests()) {
if (row.business !== state.business) continue;
const attached = stateOf(row.business, row.request);
if (attached.project === state.project && attached.phase !== 'cancelled') append(attached, 'mode.changed', { mode: args.mode, mode_revision, op: args.op, proposal_digest });
}
return stateOf(state.business, state.request);
}));
}
async function resume(business, request) {
return serial(business, request, async () => {
const state = stateOf(business, request);
if (state.wait?.code === 'prd-approval') {
try { await services.catalog.activate({ request, decision: state.wait.subject }); return stateOf(business, request); }
catch (e) {
if (e.code === 'prd-not-approved') return state;
return append(stateOf(business, request), 'prd.invalidated', { code: e.code ?? 'prd-activation-failed' });
}
}
if (state.wait?.kind !== 'decision') return runBootstrap(state);
const close = services.readDecision(business, state.selection.decision);
if (!close || close.op === 'seen') return state;
@@ -231,6 +302,21 @@ export function createRequestLifecycle({ journal, services }) {
return runBootstrap(confirmed);
});
}
return Object.freeze({ open, get, projects, propose, resume,
return Object.freeze({ open, get, projects, propose, submit, modeConsole,
draftConsole: async (identity, args) => {
exact(args, ['request']); if (!id(args.request)) refuse('invalid-request');
const state = stateOf(identity.business, args.request); authorize(identity, state, 'draft');
if (!state.candidate) refuse('prd-candidate-required');
const material = await services.readCandidate(state.candidate, state.business);
const current = stateOf(state.business, state.request); authorize(identity, current, 'draft');
if (current.revision !== state.revision) refuse('request-revision-conflict');
return { candidate: material.candidate, prd: material.prd, requirements: material.requirements };
}, resume, catalog: services.catalog,
decisionClosed: (business, decision) => {
if (closing) return Promise.resolve();
for (const row of journal.listRequests()) if (row.business === business && journal.readRequest(business, row.request).wait?.subject === decision)
return resume(business, row.request);
},
close: async () => { closing = true; await Promise.allSettled([...pending.values()]); await services.catalog?.drain(); },
recover: async () => { const states = []; for (const { business, request } of journal.listRequests()) states.push(await resume(business, request)); return states; } });
}
+102 -3
View File
@@ -48,6 +48,21 @@ export function validatePlan(p) {
try { checkVars(p.project_vars, 'project', 'request resource plan'); } catch { refuse(code); }
return p;
}
export function validateCandidate(c) {
const code = 'invalid-prd-candidate';
exact(c, ['version','request','project','prd_version','records_commit','prd_path','prd_blob','requirements','spec_commit','mode_revision'], [], code);
if (c.version !== 1 || !id(c.request) || !key(c.project) || typeof c.prd_version !== 'string' || !/^\d+\.\d+(?:\.\d+)?$/.test(c.prd_version) ||
!oid(c.records_commit) || c.prd_path !== `docs/prd-${c.prd_version}.md` || !oid(c.prd_blob) || !oid(c.spec_commit) || !positive(c.mode_revision) ||
!Array.isArray(c.requirements) || c.requirements.length < 1 || c.requirements.length > 64) refuse(code);
const seen = new Set();
for (const r of c.requirements) {
exact(r, ['id','title','path','blob'], [], code);
if (typeof r.id !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(r.id) || !text(r.title, 512) || !r.title.trim() ||
r.path !== `requirements/${r.id}.json` || !oid(r.blob) || seen.has(r.path)) refuse(code);
seen.add(r.path);
}
return c;
}
function initial(business, request, b) {
exact(b, ['source_message','thread','session','owner','pm','intent'], [], 'invalid-request-event');
if (!id(b.source_message) || !nullableId(b.thread) || !nullableId(b.session) || !id(b.owner) || !key(b.pm)) refuse('invalid-request-event');
@@ -107,6 +122,32 @@ function reduce(state, e) {
if (s.phase !== 'bootstrap' || s.plan_digest !== b.digest || b.project !== s.project || !id(b.chat_project) || !oid(b.spec_commit) || !text(b.organization_revision, 256)) refuse(code);
s.chat_project = b.chat_project; s.spec_commit = b.spec_commit; s.phase = 'discovery';
s.wait = { kind: 'setup', code: 'request-discovery-unavailable', subject: s.request, resume_phase: 'discovery', observed_revision: s.revision };
} else if (e.kind === 'prd.submitted') {
exact(b, ['candidate','decision','op','proposal_digest','authors','route'], [], code);
validateCandidate(b.candidate);
exact(b.route, ['instance','definition'], [], code);
if (!key(b.route.instance) || !key(b.route.definition)) refuse(code);
if (!['discovery','prd-review','planning'].includes(s.phase) || !id(b.decision) || !id(b.op) || !hash(b.proposal_digest) ||
b.candidate?.request !== s.request || b.candidate.project !== s.project || b.candidate.mode_revision !== s.mode_revision || !Array.isArray(b.authors) || !b.authors.length) refuse(code);
for (const a of b.authors) { exact(a, ['definition','instance','commit'], [], code); if (!key(a.definition) || !key(a.instance) || !oid(a.commit)) refuse(code); }
s.candidate = structuredClone(b.candidate); s.phase = 'prd-review'; s.snapshot = null; s.spec_commit = b.candidate.spec_commit;
s.wait = { kind: 'decision', code: 'prd-approval', subject: b.decision, resume_phase: 'prd-review', observed_revision: s.revision };
} else if (e.kind === 'prd.activated') {
exact(b, ['decision','snapshot'], [], code);
if (s.phase !== 'prd-review' || s.wait?.subject !== b.decision || !id(b.snapshot)) refuse(code);
s.snapshot = b.snapshot; s.phase = 'planning';
s.wait = { kind: 'setup', code: 'request-planning-unavailable', subject: s.request, resume_phase: 'planning', observed_revision: s.revision };
} else if (e.kind === 'prd.invalidated') {
exact(b, ['code'], [], code);
if (!text(b.code, 128)) refuse(code);
s.snapshot = null; s.candidate = null; s.phase = 'discovery';
s.wait = { kind: 'setup', code: b.code, subject: s.request, resume_phase: s.phase, observed_revision: s.revision };
} else if (e.kind === 'mode.changed') {
exact(b, ['mode','mode_revision','op','proposal_digest'], [], code);
if (!s.project || !['guided','autonomous'].includes(b.mode) || !positive(b.mode_revision) || !id(b.op) || !hash(b.proposal_digest)) refuse(code);
s.mode = b.mode; s.mode_revision = b.mode_revision;
s.candidate = null; s.snapshot = null; s.phase = 'discovery';
s.wait = { kind: 'setup', code: 'request-mode-changed', subject: s.request, resume_phase: s.phase, observed_revision: s.revision };
} else if (e.kind === 'cancelled') {
exact(b, ['decision'], [], code);
if (s.wait?.kind !== 'decision' || s.selection?.decision !== b.decision) refuse(code);
@@ -115,6 +156,12 @@ function reduce(state, e) {
return s;
}
export function createRequestStore(store) {
let composing = false;
const compose = fn => {
const before = composing; composing = true;
try { return fn(); } finally { composing = before; }
};
const atomic = fn => composing ? fn() : store.transaction(() => compose(fn));
const validateIntent = (event, origin) => {
if (event.kind === 'selection.proposed' && (!Array.isArray(event.body.bindings) ||
event.body.bindings.some(b => !object(b?.plan?.intent) || !equal(b.plan.intent, origin?.intent)))) refuse('invalid-request-event');
@@ -150,6 +197,18 @@ export function createRequestStore(store) {
if (!d || d.action !== 'project.bootstrap' || d.route_to !== 'human' || d.blocking !== 0 || d.task_ref !== null || d.requirement_ref !== null ||
d.raised_by_role !== state.pm || store.get("SELECT 1 FROM decision_events WHERE decision=? AND op IN ('resolved','withdrawn','expired')", d.id)) refuse('invalid-request-event');
}
if (e.kind === 'prd.submitted') {
const d = store.get('SELECT * FROM decisions WHERE business=? AND id=?', e.business, e.body.decision);
if (!d || d.action !== 'prd.approve' || d.project !== state.project || d.raised_by_role !== state.pm || d.raised_by_role !== e.actor.role ||
d.blocking !== 0 || d.task_ref !== null || d.requirement_ref !== null || d.route_to !== e.body.route.instance) refuse('invalid-request-event');
}
if (e.kind === 'prd.activated') {
const row = store.get('SELECT body FROM request_snapshots WHERE id=? AND business=? AND project=?', e.body.snapshot, e.business, state.project);
if (!row || JSON.parse(row.body).approval.decision !== e.body.decision) refuse('invalid-request-event');
}
if (e.kind === 'selection.confirmed' && !store.get('SELECT 1 FROM request_project_events WHERE business=? AND project=?', e.business, next.project))
store.run("INSERT INTO request_project_events(at,business,project,revision,kind,body) VALUES(?,?,?,1,'attached',?)",
new Date().toISOString(), e.business, next.project, JSON.stringify({ mode: next.mode, request: e.request }));
// A bootstrap outcome follows only from the receipts it names, so the journal cannot claim a project
// that was not activated, or retreat from one whose mapping already landed.
if (e.kind === 'bootstrap.completed' || e.kind === 'bootstrap.stale') {
@@ -170,7 +229,7 @@ export function createRequestStore(store) {
!['bootstrap','prd-submit','prd-activate','task-create','continuation','delivery'].includes(r.kind) ||
!(prepare ? r.stage === 'prepared' && r.result === null && r.code === null : ['committed','uncertain','refused'].includes(r.stage)) ||
!(r.result === null || object(r.result)) || !(r.code === null || text(r.code, 128))) refuse('invalid-request-effect');
return store.transaction(() => {
return atomic(() => {
if (!readRequest(r.business, r.request)) refuse('request-not-found');
const rows = store.all('SELECT version,business,request,op,kind,digest,stage,result,code FROM request_effects WHERE business=? AND request=? AND op=? ORDER BY seq', r.business, r.request, r.op)
.map(x => ({ ...x, result: x.result === null ? null : JSON.parse(x.result) }));
@@ -186,9 +245,19 @@ export function createRequestStore(store) {
return structuredClone(r);
});
}
return Object.freeze({ readRequest, appendRequest: e => store.transaction(() => appendInTransaction(e)),
const projectState = (business, project) => {
const row = store.get('SELECT * FROM request_project_events WHERE business=? AND project=? ORDER BY revision DESC LIMIT 1', business, project);
if (row) return { revision: row.revision, ...JSON.parse(row.body) };
// Task 1/2 databases predate mode writers. Their confirmed selection is the durable initial mode.
for (const r of store.all('SELECT DISTINCT request FROM request_events WHERE business=?', business)) {
const state = readRequest(business, r.request);
if (state.project === project && state.mode_revision > 0) return { revision: state.mode_revision, mode: state.mode, request: state.request };
}
return null;
};
return Object.freeze({ compose, readRequest, appendRequest: e => atomic(() => appendInTransaction(e)),
prepareEffect: r => receipt(r, true), finishEffect: r => receipt(r, false),
transaction: fn => store.transaction(() => fn({ appendRequest: appendInTransaction, readRequest })),
transaction: fn => atomic(() => fn({ appendRequest: appendInTransaction, readRequest })),
// Receipts read back, parsed. Hosts use these to resume a bootstrap and to rebuild readiness.
effects: (business, request) => {
if (!key(business) || !id(request)) refuse('invalid-request');
@@ -201,6 +270,36 @@ export function createRequestStore(store) {
.map(x => ({ ...x, result: x.result === null ? null : JSON.parse(x.result) }));
},
listRequests: () => store.all('SELECT DISTINCT business,request FROM request_events ORDER BY business,request'),
stateForRequest: request => {
const row = store.get('SELECT business FROM request_events WHERE request=? LIMIT 1', request);
return row ? readRequest(row.business, request) : null;
},
submission: (business, request, decision) => {
const row = store.get("SELECT body FROM request_events WHERE business=? AND request=? AND kind='prd.submitted' AND json_extract(body,'$.decision')=?", business, request, decision);
return row ? JSON.parse(row.body) : null;
},
projectState,
changeMode: ({ business, project, revision, mode, op, request }) => atomic(() => {
const last = projectState(business, project);
if ((last?.revision ?? 0) !== revision) refuse('request-mode-revision-conflict');
store.run("INSERT INTO request_project_events(at,business,project,revision,kind,body) VALUES(?,?,?,?,'mode.changed',?)",
new Date().toISOString(), business, project, revision + 1, JSON.stringify({ mode, op, request }));
return revision + 1;
}),
snapshotRequest: snapshot => store.get("SELECT request FROM request_effects WHERE kind='prd-activate' AND stage='committed' AND json_extract(result,'$.snapshot')=?", snapshot)?.request,
snapshot: snapshot => {
const row = store.get('SELECT body FROM request_snapshots WHERE id=?', snapshot);
return row ? JSON.parse(row.body) : null;
},
snapshotEvents: (business, project) => store.all('SELECT * FROM request_snapshot_events WHERE business=? AND project=? ORDER BY revision', business, project),
publishSnapshot: snapshot => store.run('INSERT INTO request_snapshots(id,at,business,project,body) VALUES(?,?,?,?,?)',
snapshot.id, new Date().toISOString(), snapshot.business, snapshot.project, JSON.stringify(snapshot)),
snapshotEvent: ({ business, project, snapshot, kind, cause }) => {
const revision = 1 + (store.get('SELECT max(revision) n FROM request_snapshot_events WHERE business=? AND project=?', business, project).n ?? 0);
store.run('INSERT INTO request_snapshot_events(at,business,project,revision,snapshot,kind,cause) VALUES(?,?,?,?,?,?,?)',
new Date().toISOString(), business, project, revision, snapshot, kind, cause);
return { snapshot, revision, kind, cause };
},
proposal: (business, request, op) => {
const row = store.get("SELECT body FROM request_events WHERE business=? AND request=? AND json_extract(body,'$.op')=? ORDER BY seq DESC LIMIT 1", business, request, op);
return row ? JSON.parse(row.body) : null;
+106
View File
@@ -0,0 +1,106 @@
// Host-only admission. The journal's readCandidate/authority/approval adapters read current host state.
import { exact, id, key, text, digest, refuse } from './request-store.mjs';
export function createRequirementCatalog({ journal, readSpec, builtinBinding }) {
const append = (state, kind, body) => journal.appendRequest({ business: state.business, request: state.request,
expectedRevision: state.revision, kind, body, actor: { role: null, run: null } });
const eventFor = snap => journal.snapshotEvents(snap.business, snap.project).filter(e => e.snapshot === snap.id).at(-1);
function invalidate(business, project, code, inTransaction = false) {
return (inTransaction ? journal.compose : journal.transaction)(() => {
const latest = new Map(journal.snapshotEvents(business, project).map(e => [e.snapshot, e]));
for (const e of latest.values()) if (e.kind === 'activated') journal.snapshotEvent({ business, project, snapshot: e.snapshot, kind: 'revoked', cause: code });
for (const row of journal.listRequests()) {
if (row.business !== business) continue;
const state = journal.readRequest(business, row.request);
if (state.project === project && (state.candidate || state.snapshot)) append(state, 'prd.invalidated', { code });
}
});
}
async function resolve(args) {
exact(args, ['business','project'], ['snapshot']);
if (!key(args.business) || !key(args.project) || (args.snapshot !== undefined && !id(args.snapshot))) refuse('invalid-request');
const { business, project } = args;
const events = journal.snapshotEvents(business, project);
const snapshot = args.snapshot ?? [...events].reverse().find(e => e.kind === 'activated')?.snapshot;
if (!snapshot) {
const builtin = await builtinBinding?.({ business, project });
if (builtin && builtin.origin === 'builtin' && builtin.business === business && builtin.project === project) return builtin;
refuse('requirement-snapshot-required');
}
const snap = journal.snapshot(snapshot);
if (!snap || snap.business !== business || snap.project !== project) refuse('requirement-snapshot-refused');
if (eventFor(snap)?.kind !== 'activated') refuse('requirement-snapshot-revoked');
const spec = await readSpec({ business, project });
const mode = journal.projectState(business, project);
if (!spec.confirmed || spec.commit !== snap.spec_commit || mode?.revision !== snap.mode_revision) {
invalidate(business, project, 'requirement-snapshot-revoked'); refuse('requirement-snapshot-revoked');
}
const state = journal.stateForRequest(journal.snapshotRequest(snap.id));
const binding = state && journal.submission(business, state.request, snap.approval.decision);
const authority = journal.authority(state, binding);
if (digest(journal.approval(state, binding)) !== digest(snap.approval)) refuse('prd-authority-refused');
// Reread immutable records, including selected-path equality at HEAD, before admitting new work.
const material = await journal.readCandidate(binding.candidate, business);
if (digest(material.candidate) !== digest(binding.candidate) || digest(material.authors) !== digest(snap.authors) ||
digest(material.candidate.requirements.map((r, i) => ({ ...r, text: material.requirements[i].text }))) !== digest(snap.requirements)) refuse('prd-candidate-stale');
if (digest(journal.authority(journal.stateForRequest(state.request), binding)) !== digest(authority) || eventFor(snap)?.kind !== 'activated' || journal.projectState(business, project)?.revision !== snap.mode_revision) refuse('requirement-snapshot-revoked');
return structuredClone(snap);
}
async function activateOnce(args) {
exact(args, ['request','decision']); if (!id(args.request) || !id(args.decision)) refuse('invalid-request');
const state = journal.stateForRequest(args.request) ?? refuse('request-not-found');
const binding = journal.submission(state.business, state.request, args.decision) ?? refuse('prd-candidate-required');
const old = journal.committed(state.business, 'prd-activate').find(e => e.request === state.request && e.result?.decision === args.decision);
if (old) return structuredClone(journal.snapshot(old.result.snapshot));
if (state.phase !== 'prd-review' || state.wait?.subject !== args.decision || digest(state.candidate) !== digest(binding.candidate)) refuse('prd-admission-revoked');
const authority = journal.authority(state, binding), approval = journal.approval(state, binding);
const material = await journal.readCandidate(binding.candidate, state.business);
if (digest(material.candidate) !== digest(binding.candidate) || digest(material.authors) !== digest(binding.authors)) refuse('prd-candidate-stale');
const spec = await readSpec({ business: state.business, project: state.project });
if (!spec.confirmed || spec.commit !== binding.candidate.spec_commit) refuse('stale-spec');
return journal.transaction(() => {
const prior = journal.committed(state.business, 'prd-activate').find(e => e.request === state.request && e.result?.decision === args.decision);
if (prior) return structuredClone(journal.snapshot(prior.result.snapshot));
const current = journal.readRequest(state.business, state.request);
if (current.revision !== state.revision || current.wait?.subject !== args.decision || journal.projectState(state.business, state.project)?.revision !== binding.candidate.mode_revision) refuse('prd-admission-revoked');
if (digest(journal.authority(current, binding)) !== digest(authority) || digest(journal.approval(current, binding)) !== digest(approval)) refuse('prd-admission-revoked');
const c = binding.candidate, snapshot = { version: 1, id: `prd-${digest({ business: state.business, candidate: c, decision: args.decision })}`,
business: state.business, project: state.project, prd_version: c.prd_version, records_commit: c.records_commit, prd_path: c.prd_path,
prd_blob: c.prd_blob, spec_commit: c.spec_commit, requirements: c.requirements.map((r, i) => ({ ...r, text: material.requirements[i].text })),
authors: material.authors, approval, mode_revision: c.mode_revision, origin: 'product' };
const header = { version: 1, business: state.business, request: state.request, op: `prd-activate:${args.decision}`, kind: 'prd-activate', digest: digest(c) };
journal.prepareEffect({ ...header, stage: 'prepared', result: null, code: null });
journal.publishSnapshot(snapshot);
journal.snapshotEvent({ business: state.business, project: state.project, snapshot: snapshot.id, kind: 'activated', cause: args.decision });
append(current, 'prd.activated', { decision: args.decision, snapshot: snapshot.id });
journal.finishEffect({ ...header, stage: 'committed', result: { snapshot: snapshot.id, decision: args.decision }, code: null });
return snapshot;
});
}
function revoke(identity, args) {
exact(args, ['project','snapshot','revision','reason','op']);
if (!key(args.project) || !id(args.snapshot) || !Number.isSafeInteger(args.revision) || args.revision < 1 || !text(args.reason, 1024) || !id(args.op)) refuse('invalid-request');
return journal.transaction(() => {
const snap = journal.snapshot(args.snapshot);
if (!snap || snap.business !== identity.business || snap.project !== args.project) refuse('requirement-snapshot-refused');
const cause = JSON.stringify({ op: args.op, reason: args.reason, by: identity.human, digest: digest(args) });
const events = journal.snapshotEvents(identity.business, args.project), old = events.find(e => e.kind === 'revoked' && e.cause === cause);
if (old) return { snapshot: old.snapshot, revision: old.revision, kind: old.kind, cause: old.cause };
if (events.some(e => { try { return JSON.parse(e.cause).op === args.op; } catch { return false; } })) refuse('request-operation-conflict');
if ((events.at(-1)?.revision ?? 0) !== args.revision) refuse('request-revision-conflict');
const result = journal.snapshotEvent({ business: identity.business, project: args.project, snapshot: snap.id, kind: 'revoked', cause });
for (const row of journal.listRequests()) {
const state = journal.readRequest(row.business, row.request);
if (row.business === identity.business && state.project === args.project && state.snapshot === snap.id) append(state, 'prd.invalidated', { code: 'requirement-snapshot-revoked' });
}
return result;
});
}
const pending = new Map();
function activate(args) {
const operation = `${args?.request}/${args?.decision}`;
if (pending.has(operation)) return pending.get(operation);
const job = activateOnce(args).finally(() => { if (pending.get(operation) === job) pending.delete(operation); });
pending.set(operation, job); return job;
}
return Object.freeze({ resolve, activate, invalidate, revoke, drain: () => Promise.allSettled([...pending.values()]) });
}
+16 -2
View File
@@ -1,3 +1,5 @@
import { createRequirementCatalog } from './requirement-catalog.mjs';
import { readPrdMaterial } from '../../project/src/prd.mjs';
import { lstatSync, readdirSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -579,11 +581,21 @@ export async function startBroker({
return no(declared ? 'project-pending' : 'project-unknown');
}
broker = new Broker({
requestLifecycle: services => (requestLifecycle = createRequestLifecycle({ journal: requestJournal, services: { ...(writer ? hostPreparation({ dataRoot, organization: writer, trackers }) : {}), ...requestServices, ...services,
requestLifecycle: services => {
const readCandidate = (candidate, business) => {
const { request, project, prd_version, records_commit, prd_path, mode_revision } = candidate;
return readPrdMaterial({ business: services.prdBusiness(business), dataRoot, request, project, prd_version, records_commit, prd_path, mode_revision,
requirement_ids: candidate.requirement_ids ?? candidate.requirements.map(r => r.id) });
};
const catalog = createRequirementCatalog({ journal: { ...requestJournal, readCandidate, authority: services.prdAuthority, approval: services.prdApproval },
readSpec: ({ business, project }) => projectModule.readSpec({ business: services.prdBusiness(business), project, dataRoot }),
builtinBinding: null });
return (requestLifecycle = createRequestLifecycle({ journal: requestJournal, services: { catalog, readCandidate, ...(writer ? hostPreparation({ dataRoot, organization: writer, trackers }) : {}), ...requestServices, ...services,
// The new-project executor needs the organization writer; without one a confirmed selection stays at its setup wait.
...(writer ? { bootstrap: ({ binding, state }) => processing.work(() => executeBootstrap({ binding, owner: state.owner, journal: requestJournal, services: {
dataRoot, organization: writer, activate: activateManagedProject, barrier: requestServices.barrier,
chat: { state: args => broker.chatProjectState(args), associate: args => broker.associateChat(args) } } })) } : {}) } })),
chat: { state: args => broker.chatProjectState(args), associate: args => broker.associateChat(args) } } })) } : {}) } }));
},
// FED R3: the access file is read per user request; a refusal leaves the user no grant.
access: access ? () => loadAccess(access.file, access.context) : null,
// FED R4 (#1801, design 3.7 trigger 1): a request stats the file and reads it only when this
@@ -978,6 +990,7 @@ export async function startBroker({
return {
broker,
requestLifecycle,
requirementCatalog: requestLifecycle.catalog,
admission,
credentials,
// P2 consumes this inside the bus only. No process IPC/verb returns it.
@@ -1048,6 +1061,7 @@ export async function startBroker({
await stopSync();
await server.close();
await adapter?.close?.();
await requestLifecycle.close();
await processing?.close();
store.close();
credentials.close();
+5 -2
View File
@@ -13,8 +13,8 @@ import { join, isAbsolute } from 'node:path';
import { createHash } from 'node:crypto';
const ddl = readFileSync(new URL('../schema.sql', import.meta.url), 'utf8');
export const SCHEMA_SHA256 = 'ae56fbdcb5ea9df3a15a47c7978f5c22516cf1c85dd9a1c9885a63bf7f80d252';
export const SCHEMA_VERSION = '3p';
export const SCHEMA_SHA256 = '2a6a161b3d671418e690942f02203b4a014e939b46ae8f651da11f091dac5455';
export const SCHEMA_VERSION = '3q';
// Ordered, named offline steps. New schema changes append a step and keep prior DDL pinned.
const legacyDDL = readFileSync(new URL('./migrations/3b.sql', import.meta.url), 'utf8');
const LEGACY_SHA256 = '179ffe356d4ff19a49b5ebad39b6c6bfd7771deb8e1b7c55b5e746f039d69e65';
@@ -93,6 +93,9 @@ const migrations = [{
from: '3o',
to: '3p',
sql: readFileSync(new URL('./migrations/3o-3p.sql', import.meta.url), 'utf8'),
}, {
from: '3p', to: '3q',
sql: readFileSync(new URL('./migrations/3p-3q.sql', import.meta.url), 'utf8'),
}];
const timedTables = [
'events',