@yemi33/minions 0.1.2424 → 0.1.2425

package/engine/api-contracts/orchestration.js

@@ -0,0 +1,602 @@
+'use strict';
+
+const keepProcesses = require('../keep-process-sweep');
+const managedSpawn = require('../managed-spawn');
+const managedSpecNameMax = managedSpawn.validateManagedSpecName('x').maxLength;
+const agentApiValidation = require('../agent-api-validation');
+
+function absentOrEmptyOperatorBody() {
+  return {
+    audit: 'audited',
+    body: {
+      policy: 'optional',
+      fields: [],
+      rationale: 'The fixed operator action accepts either no body or an empty JSON object.',
+    },
+    constraints: [
+      { kind: 'absent-or-empty-object', location: 'body' },
+    ],
+    negativeTests: [
+      { strategy: 'send-meaningful-object-body', expectedStatus: 400 },
+      { strategy: 'send-non-object-json-body', expectedStatus: 400 },
+    ],
+  };
+}
+
+module.exports = {
+  owner: 'orchestration',
+  routes: [
+    'GET /api/dispatch',
+    'GET /api/schedules',
+    'GET /api/pipelines',
+    'GET /api/keep-processes',
+    'GET /api/worktree-quarantine-refs',
+    'POST /api/keep-processes/kill',
+    'GET /api/managed-processes',
+    'GET /api/managed-processes/by-name/<name>',
+    'POST /api/managed-processes/kill',
+    'POST /api/managed-processes/restart',
+    'GET /api/managed-processes/log-stream/<name>',
+    'POST /api/engine/polling/pause',
+    'POST /api/engine/polling/resume',
+    'POST /api/engine/auto-fix/pause',
+    'POST /api/engine/auto-fix/resume',
+    'GET /api/dispatch/<id>/completion-report',
+    'POST /api/schedules/parse-natural',
+    'POST /api/schedules',
+    'POST /api/schedules/update',
+    'POST /api/schedules/delete',
+    'POST /api/schedules/run-now',
+    'GET /api/watches',
+    'GET /api/watches/target-types',
+    'GET /api/watches/action-types',
+    'GET /api/watches/<id>/history',
+    'POST /api/watches',
+    'POST /api/watches/update',
+    'POST /api/watches/delete',
+    'POST /api/pipelines',
+    'POST /api/pipelines/update',
+    'POST /api/pipelines/delete',
+    'POST /api/pipelines/trigger',
+    'POST /api/pipelines/continue',
+    'POST /api/pipelines/abort',
+    'POST /api/pipelines/retrigger',
+    'POST /api/engine/wakeup',
+    'POST /api/engine/restart',
+  ],
+  bodyless: [
+    'POST /api/engine/polling/pause',
+    'POST /api/engine/polling/resume',
+    'POST /api/engine/auto-fix/pause',
+    'POST /api/engine/auto-fix/resume',
+    'POST /api/engine/wakeup',
+    'POST /api/engine/restart',
+  ],
+  overrides: {
+    'GET /api/keep-processes': { noInput: true },
+    'GET /api/schedules': { noInput: true },
+    'GET /api/pipelines': { noInput: true },
+    'GET /api/watches': { noInput: true },
+    'GET /api/watches/target-types': { noInput: true },
+    'GET /api/watches/action-types': { noInput: true },
+    'GET /api/watches/<id>/history': {
+      audit: 'audited',
+      path: {
+        policy: 'required',
+        fields: [
+          {
+            name: 'id',
+            type: 'identifier',
+            required: true,
+            maxLength: 128,
+            allowedValuesSource: 'watches[].id',
+          },
+        ],
+      },
+      constraints: [
+        { kind: 'validated-before-history-read', field: 'id', location: 'path' },
+      ],
+      negativeTests: [
+        { strategy: 'reject-malformed-watch-id', expectedStatus: 400 },
+        { strategy: 'return-not-found-for-valid-missing-watch-id', expectedStatus: 404 },
+      ],
+    },
+    'GET /api/dispatch': {
+      audit: 'audited',
+      query: { policy: 'none', fields: [] },
+      noInputReason: 'The dispatch queue view is derived from live engine state; it consumes no caller-supplied body, path, query, or header input.',
+    },
+    'GET /api/dispatch/<id>/completion-report': {
+      audit: 'audited',
+      path: {
+        policy: 'required',
+        fields: [{
+          name: 'id',
+          type: 'identifier',
+          required: true,
+          maxLength: agentApiValidation.DISPATCH_ID_MAX_LENGTH,
+        }],
+      },
+      negativeTests: [{
+        strategy: 'reject-before-completion-report-open',
+        expectedStatus: '4xx',
+        audit: 'audited',
+      }],
+    },
+    'POST /api/engine/polling/pause': absentOrEmptyOperatorBody(),
+    'POST /api/engine/polling/resume': absentOrEmptyOperatorBody(),
+    'POST /api/engine/auto-fix/pause': absentOrEmptyOperatorBody(),
+    'POST /api/engine/auto-fix/resume': absentOrEmptyOperatorBody(),
+    'POST /api/engine/wakeup': absentOrEmptyOperatorBody(),
+    'POST /api/engine/restart': absentOrEmptyOperatorBody(),
+    'GET /api/worktree-quarantine-refs': {
+      audit: 'audited',
+      noInputReason: 'Reads quarantine refs only from configured project checkouts; accepts no caller input.',
+      constraints: [
+        {
+          kind: 'configured-project-membership',
+          source: 'config.projects[].localPath',
+        },
+      ],
+    },
+    'GET /api/managed-processes': {
+      audit: 'audited',
+      query: {
+        policy: 'optional',
+        fields: [
+          {
+            name: 'project',
+            type: 'string',
+            required: false,
+            maxLength: 64,
+            allowedValuesSource: 'config.projects[].name',
+          },
+        ],
+      },
+      constraints: [{ kind: 'single-value-query-fields' }],
+      negativeTests: [
+        { strategy: 'invalid-project-shape', expectedStatus: 400 },
+        { strategy: 'unknown-project', expectedStatus: 404 },
+      ],
+    },
+    'GET /api/managed-processes/log-stream/<name>': {
+      audit: 'audited',
+      path: {
+        policy: 'required',
+        fields: [{
+          name: 'name',
+          type: 'string',
+          required: true,
+          maxLength: managedSpecNameMax,
+          pattern: 'kebab-case',
+          validatorSource: 'managed-spawn.validateManagedSpecName',
+        }],
+      },
+      query: {
+        policy: 'optional',
+        fields: [
+          {
+            name: 'tail',
+            type: 'integer',
+            required: false,
+            default: managedSpawn.MANAGED_LOG_TAIL_DEFAULT_BYTES,
+            min: 1,
+            max: managedSpawn.MANAGED_LOG_TAIL_MAX_BYTES,
+          },
+        ],
+      },
+      constraints: [{ kind: 'single-value-query-fields' }],
+      negativeTests: [
+        { strategy: 'invalid-name-or-tail-before-state-or-file-read', expectedStatus: 400 },
+        { strategy: 'well-formed-missing-name-or-log', expectedStatus: 404 },
+      ],
+    },
+    'POST /api/keep-processes/kill': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          {
+            name: 'agentId',
+            type: 'string',
+            required: true,
+            maxLength: keepProcesses.KEEP_PROCESS_AGENT_ID_MAX,
+            pattern: '^[A-Za-z0-9][A-Za-z0-9_-]*$',
+            validatorSource: 'keep-process-sweep.isSafeKeepProcessAgentId',
+          },
+          {
+            name: 'pid',
+            type: 'integer',
+            required: true,
+            min: 1,
+            max: keepProcesses.KEEP_PROCESS_PID_MAX,
+            validatorSource: 'keep-process-sweep.validateKeepProcessPid',
+          },
+        ],
+      },
+      constraints: [
+        { kind: 'no-unknown-fields', location: 'body' },
+        { kind: 'declared-pid-required-before-kill' },
+        { kind: 'valid-keep-pids-record-required-before-kill' },
+        { kind: 'identity-bound-process-kill', source: 'process-utils.listAllProcesses' },
+      ],
+      negativeTests: [
+        { strategy: 'invalid-agent-or-pid-before-file-read-or-kill', expectedStatus: 400 },
+        { strategy: 'missing-agent-file-or-pid', expectedStatus: 404 },
+        { strategy: 'process-spy-and-file-snapshot-on-rejection', expectedStatus: '4xx' },
+      ],
+    },
+    'GET /api/managed-processes/by-name/<name>': {
+      audit: 'audited',
+      path: {
+        policy: 'required',
+        fields: [{
+          name: 'name',
+          type: 'string',
+          required: true,
+          maxLength: managedSpecNameMax,
+          pattern: 'kebab-case',
+          validatorSource: 'managed-spawn.validateManagedSpecName',
+        }],
+      },
+      negativeTests: [
+        { strategy: 'invalid-name-before-state-read', expectedStatus: 400 },
+        { strategy: 'well-formed-missing-name', expectedStatus: 404 },
+      ],
+    },
+    'POST /api/managed-processes/kill': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [{
+          name: 'name',
+          type: 'string',
+          required: true,
+          maxLength: managedSpecNameMax,
+          pattern: 'kebab-case',
+          validatorSource: 'managed-spawn.validateManagedSpecName',
+        }],
+      },
+      constraints: [
+        { kind: 'no-unknown-fields', location: 'body' },
+        {
+          kind: 'generation-and-identity-bound-process-control',
+          source: 'managed-processes pid + started_at, process-utils.getProcessIdentity',
+        },
+      ],
+      negativeTests: [
+        { strategy: 'invalid-name-before-state-read-or-kill', expectedStatus: 400 },
+        { strategy: 'well-formed-missing-name', expectedStatus: 404 },
+        { strategy: 'process-spy-zero-calls-on-rejection', expectedStatus: '4xx' },
+      ],
+    },
+    'POST /api/managed-processes/restart': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [{
+          name: 'name',
+          type: 'string',
+          required: true,
+          maxLength: managedSpecNameMax,
+          pattern: 'kebab-case',
+          validatorSource: 'managed-spawn.validateManagedSpecName',
+        }],
+      },
+      constraints: [
+        { kind: 'no-unknown-fields', location: 'body' },
+        {
+          kind: 'generation-and-identity-bound-process-control',
+          source: 'managed-processes pid + started_at, process-utils.getProcessIdentity',
+        },
+      ],
+      negativeTests: [
+        { strategy: 'invalid-name-before-state-read-kill-or-spawn', expectedStatus: 400 },
+        { strategy: 'well-formed-missing-name', expectedStatus: 404 },
+        { strategy: 'process-spy-zero-calls-on-rejection', expectedStatus: '4xx' },
+      ],
+    },
+    'POST /api/schedules/parse-natural': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'text', type: 'string', required: true, maxLengthSource: 'scheduler.SCHEDULE_LIMITS.naturalText' },
+        ],
+      },
+      constraints: [
+        { kind: 'domain-validator', source: 'scheduler.validateCronExpression (LLM result)' },
+      ],
+      negativeTests: [
+        { strategy: 'reject-non-string-or-empty-natural-language-input-before-llm', expectedStatus: 400 },
+        { strategy: 'reject-invalid-llm-cron-result', expectedStatus: 422 },
+      ],
+    },
+    'POST /api/schedules': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'id', type: 'identifier', required: false, maxLengthSource: 'scheduler.SCHEDULE_LIMITS.id' },
+          { name: 'cron', type: 'string', required: true },
+          { name: 'title', type: 'string', required: true, maxLengthSource: 'scheduler.SCHEDULE_LIMITS.title' },
+          { name: 'description', type: 'string', required: false, maxLengthSource: 'scheduler.SCHEDULE_LIMITS.description' },
+          { name: 'type', type: 'string', required: false, default: 'implement', allowedValuesSource: 'shared.WORK_TYPE' },
+          { name: 'project', type: 'string', required: false, allowedValuesSource: 'config.projects[].name' },
+          { name: 'agent', type: 'string', required: false, allowedValuesSource: 'config.agents keys' },
+          { name: 'participants', type: 'array', required: false, allowedValuesSource: 'config.agents keys' },
+          { name: 'priority', type: 'string', required: false, default: 'medium', allowedValuesSource: 'shared.WORK_ITEM_PRIORITY_VALUES' },
+          { name: 'enabled', type: 'boolean', required: false, default: true },
+        ],
+      },
+      constraints: [
+        { kind: 'domain-validator', source: 'scheduler.validateScheduleDefinition' },
+      ],
+      negativeTests: [
+        { strategy: 'reject-malformed-or-out-of-range-cron', expectedStatus: 400 },
+        { strategy: 'reject-unknown-work-type-project-agent-or-priority', expectedStatus: 400 },
+        { strategy: 'reject-non-boolean-enabled', expectedStatus: 400 },
+      ],
+    },
+    'POST /api/schedules/update': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'id', type: 'identifier', required: true, maxLengthSource: 'scheduler.SCHEDULE_LIMITS.id' },
+          { name: 'cron', type: 'string', required: false },
+          { name: 'title', type: 'string', required: false, maxLengthSource: 'scheduler.SCHEDULE_LIMITS.title' },
+          { name: 'description', type: 'string', required: false, maxLengthSource: 'scheduler.SCHEDULE_LIMITS.description' },
+          { name: 'type', type: 'string', required: false, allowedValuesSource: 'shared.WORK_TYPE' },
+          { name: 'project', type: 'string|null', required: false, allowedValuesSource: 'config.projects[].name' },
+          { name: 'agent', type: 'string|null', required: false, allowedValuesSource: 'config.agents keys' },
+          { name: 'participants', type: 'array', required: false, allowedValuesSource: 'config.agents keys' },
+          { name: 'priority', type: 'string', required: false, allowedValuesSource: 'shared.WORK_ITEM_PRIORITY_VALUES' },
+          { name: 'enabled', type: 'boolean', required: false },
+        ],
+      },
+      constraints: [
+        { kind: 'merged-candidate-domain-validator', source: 'scheduler.validateScheduleDefinition' },
+      ],
+      negativeTests: [
+        { strategy: 'reject-invalid-identifier-before-config-mutation', expectedStatus: 400 },
+        { strategy: 'reject-invalid-merged-schedule-atomically', expectedStatus: 400 },
+        { strategy: 'preserve-missing-schedule-semantics', expectedStatus: 404 },
+      ],
+    },
+    'POST /api/schedules/delete': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'id', type: 'identifier', required: true, maxLengthSource: 'scheduler.SCHEDULE_LIMITS.id' },
+        ],
+      },
+      negativeTests: [
+        { strategy: 'reject-invalid-identifier-before-config-mutation', expectedStatus: 400 },
+        { strategy: 'preserve-missing-schedule-semantics', expectedStatus: 404 },
+      ],
+    },
+    'POST /api/schedules/run-now': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'id', type: 'identifier', required: true, maxLengthSource: 'scheduler.SCHEDULE_LIMITS.id' },
+        ],
+      },
+      constraints: [
+        { kind: 'stored-definition-domain-validator', source: 'scheduler.validateScheduleDefinition' },
+      ],
+      negativeTests: [
+        { strategy: 'reject-invalid-stored-schedule-before-dispatch', expectedStatus: 400 },
+        { strategy: 'preserve-missing-schedule-semantics', expectedStatus: 404 },
+        { strategy: 'preserve-active-work-item-conflict', expectedStatus: 409 },
+      ],
+    },
+    'POST /api/pipelines': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'id', type: 'identifier', required: true, maxLengthSource: 'pipeline.PIPELINE_LIMITS.id' },
+          { name: 'title', type: 'string', required: true, maxLengthSource: 'pipeline.PIPELINE_LIMITS.title' },
+          { name: 'description', type: 'string', required: false, maxLengthSource: 'pipeline.PIPELINE_LIMITS.description' },
+          { name: 'stages', type: 'array', required: true, allowedValuesSource: 'shared.STAGE_TYPE' },
+          { name: 'trigger', type: 'object', required: false },
+          { name: 'stopWhen', type: 'string|object', required: false, allowedValuesSource: 'pipeline.PIPELINE_CONDITION_CHECKS' },
+          { name: 'monitoredResources', type: 'array', required: false },
+          { name: 'project', type: 'string', required: false, allowedValuesSource: 'config.projects[].name' },
+          { name: 'projects', type: 'array', required: false, allowedValuesSource: 'config.projects[].name' },
+          { name: 'enabled', type: 'boolean', required: false, default: true },
+        ],
+      },
+      constraints: [
+        { kind: 'recursive-plain-object-validator', source: 'pipeline.validatePipelineDefinition' },
+        { kind: 'acyclic-stage-dependency-graph' },
+        { kind: 'canonical-stage-work-type-priority-enums' },
+      ],
+      negativeTests: [
+        { strategy: 'reject-malformed-stage-graph-before-file-write', expectedStatus: 400 },
+        { strategy: 'reject-invalid-stage-specific-payload', expectedStatus: 400 },
+        { strategy: 'preserve-existing-pipeline-conflict', expectedStatus: 409 },
+      ],
+    },
+    'POST /api/pipelines/update': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'id', type: 'identifier', required: true, maxLengthSource: 'pipeline.PIPELINE_LIMITS.id' },
+          { name: 'title', type: 'string', required: false, maxLengthSource: 'pipeline.PIPELINE_LIMITS.title' },
+          { name: 'description', type: 'string', required: false, maxLengthSource: 'pipeline.PIPELINE_LIMITS.description' },
+          { name: 'stages', type: 'array', required: false, allowedValuesSource: 'shared.STAGE_TYPE' },
+          { name: 'trigger', type: 'object|null', required: false },
+          { name: 'stopWhen', type: 'string|object|null', required: false, allowedValuesSource: 'pipeline.PIPELINE_CONDITION_CHECKS' },
+          { name: 'monitoredResources', type: 'array', required: false },
+          { name: 'project', type: 'string', required: false, allowedValuesSource: 'config.projects[].name' },
+          { name: 'projects', type: 'array', required: false, allowedValuesSource: 'config.projects[].name' },
+          { name: 'enabled', type: 'boolean', required: false },
+        ],
+      },
+      constraints: [
+        { kind: 'merged-candidate-domain-validator', source: 'pipeline.validatePipelineDefinition' },
+      ],
+      negativeTests: [
+        { strategy: 'reject-invalid-merged-definition-before-file-write', expectedStatus: 400 },
+        { strategy: 'preserve-missing-pipeline-semantics', expectedStatus: 404 },
+      ],
+    },
+    'POST /api/pipelines/delete': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'id', type: 'identifier', required: true, maxLengthSource: 'pipeline.PIPELINE_LIMITS.id' },
+        ],
+      },
+      negativeTests: [
+        { strategy: 'reject-invalid-identifier-before-file-access', expectedStatus: 400 },
+        { strategy: 'preserve-missing-pipeline-semantics', expectedStatus: 404 },
+      ],
+    },
+    'POST /api/pipelines/trigger': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'id', type: 'identifier', required: true, maxLengthSource: 'pipeline.PIPELINE_LIMITS.id' },
+        ],
+      },
+      constraints: [
+        { kind: 'stored-definition-domain-validator', source: 'pipeline.validatePipelineDefinition' },
+        { kind: 'no-active-run', statusSource: 'shared.PIPELINE_STATUS' },
+      ],
+      negativeTests: [
+        { strategy: 'preserve-missing-pipeline-semantics', expectedStatus: 404 },
+        { strategy: 'preserve-active-run-conflict', expectedStatus: 409 },
+        { strategy: 'reject-invalid-definition-before-run-write', expectedStatus: 400 },
+      ],
+    },
+    'POST /api/pipelines/continue': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'id', type: 'identifier', required: true, maxLengthSource: 'pipeline.PIPELINE_LIMITS.id' },
+          { name: 'stageId', type: 'identifier', required: true, maxLengthSource: 'pipeline.PIPELINE_LIMITS.id' },
+        ],
+      },
+      constraints: [
+        { kind: 'stage-type-and-state', typeSource: 'shared.STAGE_TYPE.WAIT', statusSource: 'shared.PIPELINE_STATUS.WAITING_HUMAN' },
+      ],
+      negativeTests: [
+        { strategy: 'preserve-missing-pipeline-or-run-semantics', expectedStatus: 404 },
+        { strategy: 'reject-stage-not-waiting-with-conflict', expectedStatus: 409 },
+      ],
+    },
+    'POST /api/pipelines/abort': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'id', type: 'identifier', required: true, maxLengthSource: 'pipeline.PIPELINE_LIMITS.id' },
+        ],
+      },
+      constraints: [
+        { kind: 'active-run-required', statusSource: 'shared.PIPELINE_STATUS' },
+      ],
+      negativeTests: [
+        { strategy: 'preserve-missing-pipeline-or-active-run-semantics', expectedStatus: 404 },
+        { strategy: 'reject-invalid-identifier-before-run-or-work-item-mutation', expectedStatus: 400 },
+      ],
+    },
+    'POST /api/pipelines/retrigger': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'id', type: 'identifier', required: true, maxLengthSource: 'pipeline.PIPELINE_LIMITS.id' },
+        ],
+      },
+      constraints: [
+        { kind: 'definition-existence-and-validation-before-abort', source: 'pipeline.validatePipelineDefinition' },
+      ],
+      negativeTests: [
+        { strategy: 'preserve-missing-pipeline-without-aborting-orphan-run', expectedStatus: 404 },
+        { strategy: 'preserve-racing-active-run-conflict', expectedStatus: 409 },
+      ],
+    },
+    'POST /api/watches': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'target', type: 'string|object', required: true, allowedValuesSource: 'watches target-type registry[targetType].validateTarget' },
+          { name: 'targetType', type: 'string', required: true, allowedValuesSource: 'watches target-type registry' },
+          { name: 'condition', type: 'string', required: true, allowedValuesSource: 'watches target-type registry[targetType].conditions' },
+          { name: 'interval', type: 'integer', required: false, default: 300000, min: 60000, max: Number.MAX_SAFE_INTEGER },
+          { name: 'owner', type: 'string', required: false, default: 'human', allowedValuesSource: 'human + config.agents keys' },
+          { name: 'description', type: 'string', required: false, maxLength: 4000 },
+          { name: 'project', type: 'string|null', required: false, allowedValuesSource: 'config.projects[].name' },
+          { name: 'notify', type: 'string', required: false, default: 'inbox', allowedValues: ['inbox', 'none'] },
+          { name: 'stopAfter', type: 'integer', required: false, default: 0, min: 0, max: Number.MAX_SAFE_INTEGER },
+          { name: 'onNotMet', type: 'string|null', required: false, allowedValues: ['notify'] },
+          { name: 'action', type: 'object|array|null', required: false, allowedValuesSource: 'watch-actions registry' },
+          { name: 'requires', type: 'array|null', required: false, allowedValuesSource: 'watches target-type registry requirement conditions' },
+        ],
+      },
+      constraints: [
+        { kind: 'target-validator-by-target-type', fields: ['target', 'targetType'] },
+        { kind: 'condition-enum-by-target-type', fields: ['condition', 'targetType'] },
+        { kind: 'registered-action-validator', field: 'action' },
+        { kind: 'registered-requirement-validator', field: 'requires', maxItems: 20 },
+      ],
+      negativeTests: [
+        { strategy: 'reject-coercive-or-out-of-range-interval-and-stop-count', expectedStatus: 400 },
+        { strategy: 'reject-invalid-dynamic-target-condition-action-or-requirement', expectedStatus: 400 },
+        { strategy: 'reject-unknown-owner-or-project', expectedStatus: 400 },
+      ],
+    },
+    'POST /api/watches/update': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'id', type: 'string', required: true },
+          { name: 'status', type: 'string', required: false, allowedValuesSource: 'shared.WATCH_STATUS' },
+          { name: 'condition', type: 'string', required: false, allowedValuesSource: 'watches target-type registry[current targetType].conditions' },
+          { name: 'interval', type: 'integer', required: false, min: 60000, max: Number.MAX_SAFE_INTEGER },
+          { name: 'description', type: 'string|null', required: false, maxLength: 4000 },
+          { name: 'notify', type: 'string', required: false, allowedValues: ['inbox', 'none'] },
+          { name: 'stopAfter', type: 'integer', required: false, min: 0, max: Number.MAX_SAFE_INTEGER },
+          { name: 'onNotMet', type: 'string|null', required: false, allowedValues: ['notify'] },
+          { name: 'action', type: 'object|array|null', required: false, allowedValuesSource: 'watch-actions registry' },
+          { name: 'requires', type: 'array|null', required: false, allowedValuesSource: 'watches target-type registry requirement conditions' },
+        ],
+      },
+      constraints: [
+        { kind: 'condition-enum-by-current-target-type', fields: ['id', 'condition'] },
+        { kind: 'registered-action-validator', field: 'action' },
+        { kind: 'registered-requirement-validator', field: 'requires', maxItems: 20 },
+      ],
+      negativeTests: [
+        { strategy: 'reject-invalid-status-condition-action-or-requirement-before-mutation', expectedStatus: 400 },
+        { strategy: 'return-not-found-only-for-valid-missing-watch-id', expectedStatus: 404 },
+      ],
+    },
+    'POST /api/watches/delete': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'id', type: 'string', required: true },
+        ],
+      },
+      negativeTests: [
+        { strategy: 'reject-malformed-watch-id', expectedStatus: 400 },
+        { strategy: 'return-not-found-for-missing-watch-id', expectedStatus: 404 },
+      ],
+    },
+  },
+};