fix(admin): reconcile bounded PREPARE backend contracts

This commit is contained in:
devops committed 2026-10-23 13:04:06 +00:00
1 parent 56b6696ca3
commit f29ba4ab8b
7 files changed
+127 -31

No files matched your search

@@ -46,9 +46,57 @@ describe('orchestration adapter', () => {
expect(api.post).toHaveBeenCalledWith('/admin/orchestration/chat/messages',{sessionId:'session',message:'Review task',idempotencyKey:'key'});
});
it('creates bounded work without permitting invalid caps or client-supplied state',async()=>{
await expect(orchestration.create({key:'t',title:'Audit',department:'SEO',operationMode:'PREPARE',budgetLimitCents:-1,metadata:{scope:'staging',acceptanceCriteria:['report']}})).rejects.toThrow(/budget/);
await expect(orchestration.create({key:'t',title:'Audit',department:'SEO',operationMode:'PREPARE',budgetLimitCents:-1,metadata:{commitSha:'a'.repeat(40)}})).rejects.toThrow(/budget/);
vi.mocked(api.post).mockResolvedValue({data:{id:'new-task'}});
await orchestration.create({key:'t',title:'Audit',department:'SEO',operationMode:'PREPARE',budgetLimitCents:0,metadata:{scope:'staging',acceptanceCriteria:['report']}});
expect(api.post).toHaveBeenCalledWith('/admin/orchestration/tasks',{key:'t',title:'Audit',department:'SEO',operationMode:'PREPARE',budgetLimitCents:0,metadata:{scope:'staging',acceptanceCriteria:['report']}});
await orchestration.create({key:'t',title:'Audit',department:'SEO',operationMode:'PREPARE',budgetLimitCents:20,metadata:{commitSha:'a'.repeat(40)}});
expect(api.post).toHaveBeenCalledWith('/admin/orchestration/tasks',{key:'t',title:'Audit',department:'SEO',operationMode:'PREPARE',budgetLimitCents:20,metadata:{commitSha:'a'.repeat(40)}});
});
});
describe('actual PREPARE backend contract',()=>{
beforeEach(()=>vi.resetAllMocks());
it('normalizes strings by fixed mapping, drops unknown and tampered objects, never infers from state',async()=>{
vi.mocked(api.get).mockResolvedValue({data:{...task,state:'DRAFT',availableActions:['SUBMIT_GATE1','APPROVE_GATE1','REJECT_GATE1','QUEUE_PREPARE','RELEASE_AUTHORIZE',{id:'SUBMIT_GATE1',label:'bad',toState:'RELEASING'},null]}});
const detail=await orchestration.task('t/1');
expect(detail.availableActions.map(a=>a.id)).toEqual(['SUBMIT_GATE1','APPROVE_GATE1','REJECT_GATE1','QUEUE_PREPARE']);
vi.mocked(api.put).mockResolvedValue({data:{}});
await orchestration.command(detail,detail.availableActions[0],{idempotencyKey:'submit'});
expect(api.put).toHaveBeenCalledWith('/admin/orchestration/tasks/t%2F1/transition',{toState:'GATE1_PENDING',expectedVersion:7,idempotencyKey:'submit',reason:undefined});
vi.mocked(api.get).mockResolvedValue({data:[{...task,state:'DRAFT',availableActions:[]}]});
expect((await orchestration.tasks())[0].availableActions).toEqual([]);
});
it('rejects arbitrary object transitions and conflicting known mappings',async()=>{
vi.mocked(api.get).mockResolvedValue({data:{...task,availableActions:[{id:'evil',label:'go',toState:'RUNNING'},{id:'SUBMIT_GATE1',label:'go',toState:'READY'}]}});
expect((await orchestration.task('t/1')).availableActions).toEqual([]);
});
it.each([0,19,10001,20.5])('rejects invalid budget %s',async budget=>{
await expect(orchestration.create({key:'k',title:'t',department:'SEO',operationMode:'PREPARE',budgetLimitCents:budget,metadata:{commitSha:'a'.repeat(40)}})).rejects.toThrow(/budget/i);
expect(api.post).not.toHaveBeenCalled();
});
it.each(['abc','A'.repeat(40),'a'.repeat(64),''])('rejects invalid commit %s',async commitSha=>{
await expect(orchestration.create({key:'k',title:'t',department:'SEO',operationMode:'PREPARE',budgetLimitCents:20,metadata:{commitSha}})).rejects.toThrow(/commit/i);
});
it.each([20,10000])('posts exact DTO at boundary %s',async budget=>{
vi.mocked(api.post).mockResolvedValue({data:{}});
const dto={key:'k',title:'t',department:'SEO',operationMode:'PREPARE' as const,budgetLimitCents:budget,metadata:{commitSha:'a'.repeat(40)}};
await orchestration.create(dto);expect(api.post).toHaveBeenCalledWith('/admin/orchestration/tasks',dto);
});
});
it.each([
['APPROVE_GATE1','post','/gates/1/decide',{decision:'APPROVED'}],
['REJECT_GATE1','post','/gates/1/decide',{decision:'REJECTED'}],
['QUEUE_PREPARE','put','/transition',{toState:'READY'}],
])('routes actual advertised %s regardless of state',async(id,method,path,payload)=>{
vi.resetAllMocks();vi.mocked(api.get).mockResolvedValue({data:{...task,state:'DRAFT',availableActions:[id]}});
vi.mocked(api.post).mockResolvedValue({data:{}});vi.mocked(api.put).mockResolvedValue({data:{}});
const detail=await orchestration.task('t/1');
await orchestration.command(detail,detail.availableActions[0],{idempotencyKey:'k',expiresAt:new Date(Date.now()+3600000).toISOString()});
expect(method==='post'?api.post:api.put).toHaveBeenCalledWith('/admin/orchestration/tasks/t%2F1'+path,expect.objectContaining({...payload,expectedVersion:7,idempotencyKey:'k'}));
});
it('rejects canonical Gate1 decisions beyond backend 24 hour limit',async()=>{
vi.resetAllMocks();vi.mocked(api.get).mockResolvedValue({data:{...task,availableActions:['APPROVE_GATE1']}});
const detail=await orchestration.task('t/1');
await expect(orchestration.command(detail,detail.availableActions[0],{idempotencyKey:'k',expiresAt:'2099-01-01T00:00:00Z'})).rejects.toThrow(/24 hours/);
expect(api.post).not.toHaveBeenCalled();
});
@@ -1,5 +1,36 @@
import api from './api';
export interface ServerAction { id: string; label: string; toState?: string; gate?: 1 | 2; decision?: 'APPROVED' | 'REJECTED'; disabledReason?: string }
// Only advertised IDs select commands; task state never manufactures authorization.
const actionCommands: Record<string, ServerAction> = {
SUBMIT_GATE1:{id:'SUBMIT_GATE1',label:'Submit Gate1',toState:'GATE1_PENDING'},
APPROVE_GATE1:{id:'APPROVE_GATE1',label:'Approve Gate1',gate:1,decision:'APPROVED'},
REJECT_GATE1:{id:'REJECT_GATE1',label:'Reject Gate1',gate:1,decision:'REJECTED'},
QUEUE_PREPARE:{id:'QUEUE_PREPARE',label:'Queue PREPARE',toState:'READY'},
};
export function normalizeActions(value:unknown):ServerAction[] {
if(!Array.isArray(value))return [];
const result:ServerAction[]=[];
for(const raw of value){
let action:ServerAction|undefined;
if(typeof raw==='string')action=Object.hasOwn(actionCommands,raw)?actionCommands[raw]:undefined;
else if(raw&&typeof raw==='object'&&typeof raw.id==='string'){
const fixed=Object.hasOwn(actionCommands,raw.id)?actionCommands[raw.id]:undefined;
if(fixed){
if(['toState','gate','decision'].some(k=>raw[k]!==undefined&&raw[k]!==fixed[k as keyof ServerAction]))continue;
action={...fixed};
}else if(!raw.toState&&[1,2].includes(raw.gate)&&['APPROVED','REJECTED'].includes(raw.decision)){
// Legacy object format may describe only dedicated gate decisions, never arbitrary transitions.
action={id:raw.id,label:raw.id,gate:raw.gate,decision:raw.decision};
}
if(action){
if(typeof raw.label==='string'&&raw.label.trim())action={...action,label:raw.label};
if(typeof raw.disabledReason==='string')action={...action,disabledReason:raw.disabledReason};
}
}
if(action&&!result.some(a=>a.id===action.id))result.push({...action});
}
return result;
}
export interface Artifact { id: string; sha256: string; kind?: string; uri?: string }
export interface Run { id: string; commitSha: string; environment: string; status: string; artifacts: Artifact[] }
export interface Task { id: string; key: string; title: string; department: string; state: string; version: number; operationMode: string; budgetLimitCents: number; metadata?: Record<string, unknown>; availableActions: ServerAction[]; runs?: Run[]; decisions?: Record<string, unknown>[]; events?: Record<string, unknown>[]; budgetLedger?: Record<string, unknown>[] }
@@ -22,23 +53,28 @@ export function commandFailure(error:unknown):{message:string;retryable:boolean}
return {message:(error instanceof Error?error.message:'Backend request unavailable')+' — Outcome unknown. Retry only the identical payload/key, or refresh to reconcile.',retryable:true};
}
export type Resource = 'agents' | 'model-policy' | 'schedules' | 'releases' | 'overview';
export interface ResourceSnapshot { capabilities?: {mutations:boolean;chat:boolean;runtime:boolean}; items: Array<{id:string; title?:string; status?:string; department?:string; readiness?:string; model?:string; budgetLimitCents?:number; spentCents?:number; cron?:string; timezone?:string; environment?:string; commitSha?:string; reason?:string}>; measuredAt: string }
export interface ResourceSnapshot { capabilities?: {mutations:boolean;chat:boolean;runtime:boolean;killSwitch?:boolean}; items: Array<{id:string; title?:string; status?:string; department?:string; readiness?:string; model?:string; budgetLimitCents?:number; spentCents?:number; cron?:string; timezone?:string; environment?:string; commitSha?:string; reason?:string}>; measuredAt: string }
export const killLevels = ['FREEZE_NEW_WORK','STOP_AGENTS','DISABLE_MUTATIONS','EMERGENCY_HALT'] as const;
export type KillLevel = typeof killLevels[number];
export interface ChatMessage {id:string;role:'assistant'|'user';content:string}
function unwrap<T>(data: T | {success:boolean;data:T}): T { if (data && typeof data === 'object' && 'success' in data) {if (!data.success) throw new Error('Orchestration request failed'); return data.data;} return data as T; }
export interface CreateTaskInput {key:string;title:string;department:string;operationMode:'OBSERVE'|'PREPARE'|'MUTATE_PRODUCTION';budgetLimitCents:number;metadata:{scope:string;acceptanceCriteria:string[]}}
export interface CreateTaskInput {key:string;title:string;department:string;operationMode:'PREPARE';budgetLimitCents:number;metadata:{commitSha:string}}
export function proposalError(input:CreateTaskInput):string|undefined {
if(input.operationMode!=='PREPARE')return 'Only bounded Stage PREPARE proposals are available';
if(!Number.isSafeInteger(input.budgetLimitCents)||input.budgetLimitCents<20||input.budgetLimitCents>10000)return 'PREPARE budget must be an integer 20..10000 cents';
if(!/^[a-f0-9]{40}$/.test(input.metadata?.commitSha??''))return 'Immutable commit must be 40 lowercase hex characters';
if(!input.key.trim()||input.key.length>120||!input.title.trim()||input.title.length>255||!input.department.trim()||input.department.length>50)return 'Proposal requires key (1..120), title (1..255), department (1..50)';
}
export const orchestration = {
async create(input:CreateTaskInput):Promise<unknown> {
if(input.operationMode==='MUTATE_PRODUCTION')throw new Error('Production proposals are unavailable in this panel');
if(!Number.isSafeInteger(input.budgetLimitCents)||input.budgetLimitCents<0)throw new Error('Nonnegative integer budget required');
if(!input.key.trim()||!input.title.trim()||!input.department.trim()||!input.metadata.scope.trim()||!input.metadata.acceptanceCriteria.length)throw new Error('Bounded scope and acceptance criteria required');
return (await api.post('/admin/orchestration/tasks',{key:input.key,title:input.title,department:input.department,operationMode:input.operationMode,budgetLimitCents:input.budgetLimitCents,metadata:input.metadata})).data;
const error=proposalError(input);if(error)throw new Error(error);
// Backend fixes scope/environment and does not persist free-form acceptance fields.
return (await api.post('/admin/orchestration/tasks',{key:input.key,title:input.title,department:input.department,operationMode:'PREPARE',budgetLimitCents:input.budgetLimitCents,metadata:{commitSha:input.metadata.commitSha}})).data;
},
async task(id:string):Promise<Task> {
const data=unwrap<Task>((await api.get('/admin/orchestration/tasks/'+encodeURIComponent(id))).data);
if (!data?.id || !Number.isInteger(data.version)) throw new Error('Invalid task detail');
return {...data,availableActions:data.availableActions??[]};
return {...data,availableActions:normalizeActions(data.availableActions)};
},
async resource(name:Resource):Promise<ResourceSnapshot> {
const data=unwrap<ResourceSnapshot>((await api.get('/admin/orchestration/'+name)).data);
@@ -56,13 +92,14 @@ export const orchestration = {
return data;
},
async command(task: Task, requested: ServerAction, input: CommandInput): Promise<unknown> {
const action = task.availableActions.find(a => a.id === requested.id);
const action = normalizeActions(task.availableActions).find(a => a.id === requested.id);
if (!action || action.disabledReason) throw new Error('Action is not advertised or is disabled');
const blocked=actionBlockReason(task,action);if(blocked)throw new Error(blocked);
if (!input.idempotencyKey || !Number.isInteger(task.version)) throw new Error('Version and idempotency key required');
const base = '/admin/orchestration/tasks/' + encodeURIComponent(task.id);
if (action.gate && action.decision) {
if (!input.expiresAt || !(Date.parse(input.expiresAt) > Date.now())) throw new Error('Future expiry required');
if(['APPROVE_GATE1','REJECT_GATE1'].includes(action.id)&&Date.parse(input.expiresAt)>Date.now()+86400000)throw new Error('Gate1 expiry must be within 24 hours');
let binding = {};
if (action.gate === 2 && action.decision === 'APPROVED') {
const run = task.runs?.find(r => r.id === input.runId);
@@ -79,6 +116,6 @@ export const orchestration = {
const { data } = await api.get('/admin/orchestration/tasks');
const rows = Array.isArray(data) ? data : data.data;
if (!Array.isArray(rows)) throw new Error('Invalid orchestration task response');
return rows.map(row => ({ ...row, availableActions: row.availableActions ?? [] }));
return rows.map(row => ({ ...row, availableActions: normalizeActions(row.availableActions) }));
},
};