Preserve bounded PREPARE scope and normalize proposal conflicts

This commit is contained in:
devops committed 2026-10-23 13:03:33 +00:00
1 parent 5b4d099d80
commit d43aa02b01
4 files changed
+278 -37

No files matched your search

+10 -4
View File
@@ -10,16 +10,16 @@ Base `/admin/orchestration`:
- `GET /tasks`: task array.
- `GET /tasks/:id`: task object.
- `GET /overview`: existing inventory items plus capabilities `{mutations:true, prepare:true, release:false, gate2Decisions:false, chat:false, runtime:false}`, reason `bounded_stage_prepare_only`.
- `POST /tasks`: existing CreateOrchestrationTaskDto `{key,title,department,operationMode:"PREPARE",budgetLimitCents,metadata:{commitSha}}`; commitSha is lowercase 40hex; budget is integer 20..10000 cents. Returns 201 projected task, state DRAFT/version1. Metadata input scope/profile/actor/other arbitrary keys are discarded. Key max120, title max255, department max50. Proposal key is unique; create replay should fetch existing task rather than retry blindly.
- `POST /tasks`: existing CreateOrchestrationTaskDto `{key,title,department,operationMode:"PREPARE",budgetLimitCents,metadata:{commitSha,scope,acceptanceCriteria}}`; commitSha is required lowercase 40hex; scope is a non-blank string of at most 2000 characters; acceptanceCriteria is 1..20 non-blank strings of at most 500 characters each; budget is integer 20..10000 cents. Returns 201 projected task, state DRAFT/version1. Validated scope and acceptance criteria are persisted exactly and remain unchanged by workflow transitions. The internal `workflowScope:"STAGE_PREPARE"`, environment and createdBy are server-owned; input profile/actor/other arbitrary keys are discarded. Key max120, title max255, department max50. Proposal key is unique; sequential or concurrent duplicate keys return 409, without updating the original task or appending another proposal event. Fetch/reconcile the existing task rather than retry blindly.
- `PUT /tasks/:id/transition`: `{toState:"GATE1_PENDING"|"READY",expectedVersion,idempotencyKey,reason?}`. Only DRAFT->GATE1_PENDING and GATE1_APPROVED->READY. Owner or SUPER_ADMIN. Returns 200 projected task. READY atomically creates dispatch outbox. Requires unexpired Gate1.
- `POST /tasks/:id/gates/1/decide`: existing GateDecisionDto `{decision:"APPROVED"|"REJECTED",expectedVersion,idempotencyKey,expiresAt,notes?}`. SUPER_ADMIN independent from proposer. Future expiry <=24h. Returns 201 **projected task**, not decision object.
- Gate2 decision, budget writes/reconcile, command routes (including release), chat and kill-switch HTTP mutations remain 403. Runtime resource reads remain 503.
Task projection keeps existing scalar fields and safe nested runs/artifacts, decisions, events and ledger. Adds only `metadata:{scope:"STAGE_PREPARE",environment:"staging",commitSha}` for bounded proposals, otherwise `{}`. Never includes createdBy, payloads, URI, signatures, tokens or lease credentials.
Task projection keeps existing scalar fields and safe nested runs/artifacts, decisions, events and ledger. Adds only `metadata:{scope,acceptanceCriteria,environment:"staging",commitSha}` for bounded proposals, otherwise `{}`. Never includes createdBy, workflowScope, payloads, URI, signatures, tokens or lease credentials. Pre-fix rows with the legacy scope sentinel remain readable/operable but have no recovered acceptance criteria: do not represent those as complete immutable scope review evidence.
`availableActions:string[]` is state/identity-derived: DRAFT owner -> `SUBMIT_GATE1`; GATE1_PENDING independent SUPER_ADMIN -> `APPROVE_GATE1`,`REJECT_GATE1`; GATE1_APPROVED owner/SUPER_ADMIN -> `QUEUE_PREPARE`; all worker/verification/Gate2 and legacy states -> `[]`. Actions indicate workflow eligibility, not a guarantee: current kill switch, approval expiry and concurrent versions are rechecked transactionally on mutation. Panel must not infer actions from state or send actor identity.
Common errors: 400 invalid DTO/binding; 403 wrong scope/identity/independence/kill/budget/expiry; 409 stale version or idempotency payload mismatch. Transition/decision replay returns current persisted task and does not duplicate side effects.
Common errors: 400 invalid DTO/binding; 403 wrong scope/identity/independence/kill/budget/expiry; 409 duplicate proposal key, stale version or idempotency payload mismatch. Transition/decision replay returns current persisted task and does not duplicate side effects.
## Internal service contracts (NOT browser endpoints)
`PrepareWorkflowService` is exported by OrchestrationModule. Trusted backend composition must override `PREPARE_WORKFLOW_CONFIG` with explicit `workerIds` and `stageCiIds`, default both empty. Do not populate from request bodies or user-selected runtime profiles. Worker identities require role WORKFLOW_WORKER AND ID allowlist; Stage identities require STAGE_CI AND separate ID allowlist. Credential/session provisioning and transport remain the integrating runtime owner's responsibility.
@@ -34,4 +34,10 @@ Real isolated PostgreSQL16, no published ports/no live volumes. Added migrations
DB regressions: concurrent claim winner, queue race/replay mismatch, hard budget rollback, stale lease fencing, max3 attempts, conservative expired costs, kill switch, self approval, trusted IDs, QA reconciliation and Stage evidence to Gate2 pending. Test fixture artifact URIs/hashes are not real deployment evidence.
Remaining: actual authenticated runtime worker transport/executor and pinned CI evidence transport; shared department/company budget model and locking (NOT implemented or represented by fake totals); retry backoff/dead-letter UX/cancellation; hard total execution wall-time; durable request replay of completion/evidence; duplicate proposal-key HTTP conflict normalization; kill-switch concurrent insertion/version locking; migration rehearsal with full legacy schema; real Stage CI artifact/deployment verification. No push/deploy/live DB/runtime edits. Production release remains denied at HTTP boundary; unsafe legacy core release method is deliberately untouched and must never be called by this slice.
Remaining: actual authenticated runtime worker transport/executor and pinned CI evidence transport; shared department/company budget model and locking (NOT implemented or represented by fake totals); retry backoff/dead-letter UX/cancellation; hard total execution wall-time; durable request replay of completion/evidence; kill-switch concurrent insertion/version locking; migration rehearsal with full legacy schema; real Stage CI artifact/deployment verification. No push/deploy/live DB/runtime edits. Production release remains denied at HTTP boundary; unsafe legacy core release method is deliberately untouched and must never be called by this slice.
## Contract repair verification
Actual frontend inspection confirmed proposal submission sent human scope and acceptanceCriteria but omitted required commitSha. Frontend repair is separately assigned; no frontend file changed here. New proposals now require all three fields. Internal Stage restriction uses a separate server-owned workflowScope marker rather than overwriting user scope. No metadata update route exists in this bounded workflow.
TDD RED→GREEN against isolated PostgreSQL16 reproduced dropped scope/criteria, nine invalid metadata acceptances (including array-to-string commit coercion), and duplicate-key P2002 leakage. Final database suite: 24 cases, including authenticated HTTP create/list/detail persistence, 400 validation, and 409 duplicate responses. Full allowed backend regression: 106 suites / 868 tests passed; legacy orchestration.integration.spec.ts excluded to avoid executing RELEASE_AUTHORIZE. Build exit0. Scoped lint remains failing on inherited require-await/no-unnecessary-type-assertion errors (13 errors); no lint suppression or config change applied. Disposable DB only; no live edits/push/deploy.
@@ -75,7 +75,11 @@ describe('bounded workflow HTTP contracts', () => {
department: 'ENGINEERING',
operationMode: 'PREPARE',
budgetLimitCents: 20,
metadata: { commitSha: 'a'.repeat(40) },
metadata: {
commitSha: 'a'.repeat(40),
scope: 'Staging audit only',
acceptanceCriteria: ['QA passes'],
},
};
const r = await request(app.getHttpServer())
.post('/admin/orchestration/tasks')
@@ -49,7 +49,10 @@ export class PrepareWorkflowService {
await tx.$queryRaw`SELECT id FROM orchestration_tasks WHERE id = ${id}::uuid FOR UPDATE`;
const t = await tx.orchestrationTask.findUnique({ where: { id } });
if (!t) throw new NotFoundException('Task not found');
if (t.operationMode !== 'PREPARE' || t.metadata?.scope !== 'STAGE_PREPARE')
if (
t.operationMode !== 'PREPARE' ||
(t.metadata?.workflowScope ?? t.metadata?.scope) !== 'STAGE_PREPARE'
)
throw new ForbiddenException('Not a bounded Stage proposal');
return t;
}
@@ -103,6 +106,27 @@ export class PrepareWorkflowService {
}
async create(dto: any, a: WorkflowIdentity) {
this.identity(a, ['Admin', 'SUPER_ADMIN']);
const metadata = dto?.metadata;
const boundedText = (value: unknown, max: number) =>
typeof value === 'string' &&
value.trim().length > 0 &&
value.length <= max;
if (
!metadata ||
typeof metadata !== 'object' ||
Array.isArray(metadata) ||
typeof metadata.commitSha !== 'string' ||
!boundedText(metadata.scope, 2000) ||
!Array.isArray(metadata.acceptanceCriteria) ||
metadata.acceptanceCriteria.length < 1 ||
metadata.acceptanceCriteria.length > 20 ||
!metadata.acceptanceCriteria.every((criterion: unknown) =>
boundedText(criterion, 500),
)
)
throw new BadRequestException(
'PREPARE requires commitSha, scope 1..2000 characters and 1..20 acceptance criteria of 1..500 characters',
);
if (
dto.operationMode !== 'PREPARE' ||
!/^[a-f0-9]{40}$/.test(dto.metadata?.commitSha ?? '') ||
@@ -122,35 +146,49 @@ export class PrepareWorkflowService {
dto.department.length > 50
)
throw new BadRequestException('Invalid proposal fields');
return this.db.$transaction(async (tx: any) => {
await this.allowed(tx, true);
const t = await tx.orchestrationTask.create({
data: {
key: dto.key,
title: dto.title,
department: dto.department,
operationMode: 'PREPARE',
budgetLimitCents: dto.budgetLimitCents,
metadata: {
scope: 'STAGE_PREPARE',
environment: 'staging',
commitSha: dto.metadata.commitSha,
createdBy: a.id,
return this.db
.$transaction(async (tx: any) => {
await this.allowed(tx, true);
const t = await tx.orchestrationTask.create({
data: {
key: dto.key,
title: dto.title,
department: dto.department,
operationMode: 'PREPARE',
budgetLimitCents: dto.budgetLimitCents,
metadata: {
workflowScope: 'STAGE_PREPARE',
scope: dto.metadata.scope,
acceptanceCriteria: [...dto.metadata.acceptanceCriteria],
environment: 'staging',
commitSha: dto.metadata.commitSha,
createdBy: a.id,
},
state: 'DRAFT',
},
state: 'DRAFT',
},
});
await tx.orchestrationEvent.create({
data: {
taskId: t.id,
sequence: 1,
eventType: 'PREPARE_PROPOSED',
actorId: a.id,
toState: 'DRAFT',
},
});
return t;
})
.catch((error: any) => {
if (
error?.code === 'P2002' &&
Array.isArray(error.meta?.target) &&
error.meta.target.includes('key')
)
throw new ConflictException(
'Proposal key already exists; fetch and reconcile the existing task',
);
throw error;
});
await tx.orchestrationEvent.create({
data: {
taskId: t.id,
sequence: 1,
eventType: 'PREPARE_PROPOSED',
actorId: a.id,
toState: 'DRAFT',
},
});
return t;
});
}
async transition(id: string, dto: any, a: WorkflowIdentity) {
this.identity(a, ['Admin', 'SUPER_ADMIN']);
@@ -488,7 +526,8 @@ export class PrepareWorkflowService {
}
project(t: any, a: WorkflowIdentity) {
const safe =
t.operationMode === 'PREPARE' && t.metadata?.scope === 'STAGE_PREPARE';
t.operationMode === 'PREPARE' &&
(t.metadata?.workflowScope ?? t.metadata?.scope) === 'STAGE_PREPARE';
const owner =
a?.id && (t.metadata?.createdBy === a.id || a.role === 'SUPER_ADMIN');
const actions: string[] = [];
@@ -506,7 +545,10 @@ export class PrepareWorkflowService {
...t,
metadata: safe
? {
scope: 'STAGE_PREPARE',
scope: t.metadata.scope,
...(t.metadata.workflowScope === 'STAGE_PREPARE'
? { acceptanceCriteria: t.metadata.acceptanceCriteria }
: {}),
environment: 'staging',
commitSha: t.metadata.commitSha,
}
+191 -2
View File
@@ -1,3 +1,9 @@
import { Test } from '@nestjs/testing';
import request from 'supertest';
import { OrchestrationController } from './orchestration.controller';
import { OrchestrationService } from './orchestration.service';
import { JwtAuthGuard } from '../auth/jwt-auth.guard';
import { RolesGuard } from '../common/guards/roles.guard';
import { PrismaClient } from '@prisma/client';
import { PrepareWorkflowService } from './prepare-workflow.service';
import { OperationMode, WorkflowState } from './orchestration.domain';
@@ -23,7 +29,8 @@ const enabled = process.env.WORKFLOW_DB === '1';
metadata: {
commitSha: 'a'.repeat(40),
token: 'must-not-persist',
scope: 'production',
scope: 'Staging schema audit only',
acceptanceCriteria: ['Report all schema failures'],
actorId: 'spoof',
},
});
@@ -62,6 +69,187 @@ const enabled = process.env.WORKFLOW_DB === '1';
afterAll(async () => {
await db.$disconnect();
});
it('persists and projects immutable bounded proposal scope without arbitrary metadata', async () => {
const input = dto();
const t = await service.create(input, admin);
expect(t.metadata).toMatchObject({
workflowScope: 'STAGE_PREPARE',
scope: input.metadata.scope,
acceptanceCriteria: input.metadata.acceptanceCriteria,
commitSha: input.metadata.commitSha,
});
expect(t.metadata).not.toHaveProperty('token');
expect(t.metadata).not.toHaveProperty('actorId');
const submitted = await service.transition(
t.id,
{
toState: 'GATE1_PENDING',
expectedVersion: t.version,
idempotencyKey: `immutable-${t.id}`,
},
admin,
);
expect(submitted.metadata).toEqual(t.metadata);
expect(service.project(submitted, reviewer).metadata).toEqual({
scope: input.metadata.scope,
acceptanceCriteria: input.metadata.acceptanceCriteria,
environment: 'staging',
commitSha: input.metadata.commitSha,
});
});
it.each([
null,
[],
{},
{ commitSha: 'a'.repeat(40), scope: '', acceptanceCriteria: ['ok'] },
{
commitSha: 'a'.repeat(40),
scope: ' '.repeat(10),
acceptanceCriteria: ['ok'],
},
{
commitSha: 'a'.repeat(40),
scope: 'x'.repeat(2001),
acceptanceCriteria: ['ok'],
},
{ commitSha: 'a'.repeat(40), scope: 'ok', acceptanceCriteria: [] },
{
commitSha: 'a'.repeat(40),
scope: 'ok',
acceptanceCriteria: Array(21).fill('ok'),
},
{
commitSha: 'a'.repeat(40),
scope: 'ok',
acceptanceCriteria: ['x'.repeat(501)],
},
{ commitSha: 'a'.repeat(40), scope: 'ok', acceptanceCriteria: [' '] },
{ commitSha: 'a'.repeat(40), scope: 'ok', acceptanceCriteria: [123] },
{ commitSha: ['a'.repeat(40)], scope: 'ok', acceptanceCriteria: ['ok'] },
{ scope: 'ok', acceptanceCriteria: ['ok'] },
])(
'rejects unsafe or unbounded metadata %# without persisting',
async (metadata) => {
const input = { ...dto(), metadata };
await expect(service.create(input, admin)).rejects.toMatchObject({
status: 400,
});
expect(
await db.orchestrationTask.count({ where: { key: input.key } }),
).toBe(0);
},
);
it('accepts exact metadata bounds', async () => {
const metadata = {
commitSha: 'a'.repeat(40),
scope: 'x'.repeat(2000),
acceptanceCriteria: Array(20).fill('x'.repeat(500)),
};
expect(
(await service.create({ ...dto(), metadata }, admin)).metadata,
).toMatchObject(metadata);
});
it('normalizes racing duplicate proposal keys to conflict without duplicate events', async () => {
const input = dto();
const results = await Promise.allSettled([
service.create(input, admin),
service.create({ ...input, title: 'Different intent' }, reviewer),
]);
expect(results.filter((r) => r.status === 'fulfilled')).toHaveLength(1);
const rejected = results.find(
(r) => r.status === 'rejected',
) as PromiseRejectedResult;
expect(rejected.reason).toMatchObject({ status: 409 });
const persisted = await db.orchestrationTask.findUniqueOrThrow({
where: { key: input.key },
});
expect(
await db.orchestrationEvent.count({ where: { taskId: persisted.id } }),
).toBe(1);
await expect(service.create(input, admin)).rejects.toMatchObject({
status: 409,
});
});
it('enforces create and read contracts over HTTP with real PostgreSQL persistence', async () => {
const module = await Test.createTestingModule({
controllers: [OrchestrationController],
providers: [
{ provide: PrepareWorkflowService, useValue: service },
{
provide: OrchestrationService,
useValue: {
findAll: () => db.orchestrationTask.findMany(),
findOne: (id: string) =>
db.orchestrationTask.findUniqueOrThrow({ where: { id } }),
},
},
],
})
.overrideGuard(JwtAuthGuard)
.useValue({
canActivate(context: any) {
context.switchToHttp().getRequest().user = {
sub: admin.id,
role: admin.role,
};
return true;
},
})
.overrideGuard(RolesGuard)
.useValue({ canActivate: () => true })
.compile();
const app = module.createNestApplication();
await app.init();
try {
const input = dto();
const response = await request(app.getHttpServer())
.post('/admin/orchestration/tasks')
.send(input)
.expect(201);
expect(response.body.metadata).toEqual({
scope: input.metadata.scope,
acceptanceCriteria: input.metadata.acceptanceCriteria,
commitSha: input.metadata.commitSha,
environment: 'staging',
});
expect(response.body.availableActions).toEqual(['SUBMIT_GATE1']);
const detail = await request(app.getHttpServer())
.get(`/admin/orchestration/tasks/${response.body.id}`)
.expect(200);
expect(detail.body.metadata).toEqual(response.body.metadata);
const list = await request(app.getHttpServer())
.get('/admin/orchestration/tasks')
.expect(200);
expect(
list.body.find((row: any) => row.id === response.body.id).metadata,
).toEqual(response.body.metadata);
expect(JSON.stringify(response.body)).not.toMatch(
/createdBy|must-not-persist|actorId|workflowScope/,
);
await request(app.getHttpServer())
.post('/admin/orchestration/tasks')
.send(input)
.expect(409);
await request(app.getHttpServer())
.post('/admin/orchestration/tasks')
.send({
...input,
key: `${input.key}-invalid`,
metadata: { scope: 'only stage', acceptanceCriteria: ['QA passes'] },
})
.expect(400);
await request(app.getHttpServer())
.post('/admin/orchestration/tasks')
.send({
...input,
key: `${input.key}-invalid`,
metadata: { ...input.metadata, acceptanceCriteria: [' '] },
})
.expect(400);
} finally {
await app.close();
}
});
it('fences heartbeat and completes QA plus independent Stage evidence only to Gate2 pending', async () => {
const t = await ready();
const c = await service.claim(worker, t.id);
@@ -315,7 +503,8 @@ const enabled = process.env.WORKFLOW_DB === '1';
),
).toMatchObject({
metadata: {
scope: 'STAGE_PREPARE',
scope: 'Staging schema audit only',
acceptanceCriteria: ['Report all schema failures'],
environment: 'staging',
commitSha: 'a'.repeat(40),
},