@nodii/dev 0.5.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.md +83 -1
  2. package/dist/api.js +10 -2
  3. package/dist/cli.js +24 -2
  4. package/dist/core.js +24 -6
  5. package/dist/devops-openapi.json +1 -1
  6. package/dist/docs.js +204 -0
  7. package/dist/harness.js +343 -0
  8. package/dist/upload.js +291 -0
  9. package/package.json +3 -2
package/dist/devops-openapi.json CHANGED
@@ -1 +1 @@
1
- {"openapi":"3.1.0","info":{"title":"Nodii Dev API","version":"0.1.0","description":"Dev, reached only through the platform edge at /devops/api/v1/* with a nodii-auth OAuth bearer (the platform tenant's nodii-dev app, D1368)."},"servers":[{"url":"https://platform.nucleus-cloud.in/devops"}],"components":{"securitySchemes":{"oauth":{"type":"http","scheme":"bearer","description":"nodii-auth OAuth access token"}},"schemas":{"HealthResponse":{"type":"object","properties":{"status":{"type":"string","const":"ok"},"at":{"type":"string"},"rbacCatalog":{"type":"object","properties":{"domainKey":{"type":"string"},"catalogVersion":{"type":"string"},"status":{"type":"string","enum":["disabled","pending","published","degraded"]},"attempts":{"type":"integer","minimum":0}},"required":["domainKey","catalogVersion","status","attempts"]}},"required":["status","at","rbacCatalog"]},"Service":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"wave":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["planned","feature_docs_drafting","contracts_authoring","scaffolding","implementing","partially_implemented","implemented","live","active","deprecated","frozen"]},"owner":{"type":["string","null"]},"repoUrl":{"type":["string","null"]},"description":{"type":["string","null"]},"activeImplementerAgentId":{"type":["string","null"],"format":"uuid"},"lastImplSessionAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","wave","status","owner","repoUrl","description","activeImplementerAgentId","lastImplSessionAt","createdAt","updatedAt"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"boolean","const":true},"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["error","code"]},"ServiceInsert":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"name":{"type":"string"},"wave":{"type":"integer","minimum":0,"maximum":5},"status":{"type":"string","enum":["planned","feature_docs_drafting","contracts_authoring","scaffolding","implementing","partially_implemented","implemented","live","active","deprecated","frozen"]},"owner":{"type":["string","null"]},"repoUrl":{"type":["string","null"]},"description":{"type":["string","null"]},"activeImplementerAgentId":{"type":["string","null"],"format":"uuid"},"lastImplSessionAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","wave"]},"ServiceStatusFacts":{"type":"object","properties":{"serviceId":{"type":"string"},"featureDocsTotal":{"type":"number"},"featureDocsImplemented":{"type":"number"},"featureDocsPartiallyImplemented":{"type":"number"},"featureDocsImplementing":{"type":"number"},"contractsTotal":{"type":"number"},"hasActiveImplementer":{"type":"boolean"}},"required":["serviceId","featureDocsTotal","featureDocsImplemented","featureDocsPartiallyImplemented","featureDocsImplementing","contractsTotal","hasActiveImplementer"]},"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sessionId":{"type":"string"},"serviceId":{"type":["string","null"]},"name":{"type":"string"},"personId":{"type":["string","null"]},"oauthAppClientId":{"type":["string","null"]},"oauthAppInstallationId":{"type":["string","null"]},"appGrantPermissionKeys":{"type":"array","items":{"type":"string"}},"machineId":{"type":["string","null"],"format":"uuid"},"role":{"type":"string","enum":["coordinator","agent"]},"homeRepo":{"type":["string","null"]},"laneLimit":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["active","idle","disconnected"]},"heartbeatIntervalSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"authenticationMethod":{"type":"string"},"lastSeenAt":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","sessionId","serviceId","name","personId","oauthAppClientId","oauthAppInstallationId","appGrantPermissionKeys","machineId","role","homeRepo","laneLimit","status","heartbeatIntervalSeconds","authenticationMethod","lastSeenAt","createdAt"]},"AgentRegister":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sessionId":{"type":"string"},"serviceId":{"type":["string","null"]},"name":{"type":"string"},"personId":{"type":["string","null"]},"oauthAppClientId":{"type":["string","null"]},"oauthAppInstallationId":{"type":["string","null"]},"appGrantPermissionKeys":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","idle","disconnected"]},"heartbeatIntervalSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"authenticationMethod":{"type":"string"},"lastSeenAt":{"type":"string"},"createdAt":{"type":"string"}},"required":["sessionId","name"]},"AgentWakeupResult":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"at":{"type":"string"},"status":{"type":"string","enum":["in_progress","compiling","testing","awaiting_review","blocked","complete","released","failed-validation"]},"commitSha":{"type":["string","null"]},"notes":{"type":["string","null"]},"nextWakeupHint":{"type":["string","null"],"enum":["normal","fast","slow","awaiting-external",null]}},"required":["id","agentId","at","status","commitSha","notes","nextWakeupHint"]},"GlobalDoctrine":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"path":{"type":"string"},"version":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"title":{"type":"string"},"kind":{"type":"string","enum":["global","workflow","module"]},"scope":{"type":["string","null"]},"enforcement":{"type":["string","null"]},"decisionRefs":{"type":"array","items":{"type":"string"}},"bodyS3Key":{"type":"string"},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"sourceSha":{"type":["string","null"]},"supersedesId":{"type":["string","null"],"format":"uuid"},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"deprecatedAt":{"type":["string","null"]},"deprecatedReason":{"type":["string","null"]},"deprecatedByAgentId":{"type":["string","null"],"format":"uuid"}},"required":["id","path","version","title","kind","scope","enforcement","decisionRefs","bodyS3Key","bodySha256","bodyBytes","sourceSha","supersedesId","createdByAgentId","createdAt","deprecatedAt","deprecatedReason","deprecatedByAgentId"]},"Decision":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"module":{"type":"string"},"topicTags":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["pending","locked","superseded"]},"bodyS3Key":{"type":"string"},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"supersedesId":{"type":["string","null"]},"supersededById":{"type":["string","null"]},"lockedAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","title","module","topicTags","status","bodyS3Key","bodySha256","bodyBytes","supersedesId","supersededById","lockedAt","createdAt","updatedAt"]},"DecisionAmendment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"decisionId":{"type":"string"},"amendedByDecisionId":{"type":"string"},"noteMd":{"type":"string"},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"}},"required":["id","decisionId","amendedByDecisionId","noteMd","createdByAgentId","createdAt"]},"FeatureDoc":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"docKey":{"type":"string"},"version":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"title":{"type":"string"},"area":{"type":["string","null"]},"decisionRefs":{"type":"array","items":{"type":"string"}},"bodyS3Key":{"type":"string"},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["planned","approved","implementing","partially_implemented","implemented","superseded"]},"claimedByAgentId":{"type":["string","null"],"format":"uuid"},"claimExpiresAt":{"type":["string","null"]},"completionPct":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"shippedAt":{"type":["string","null"]},"implementationCommitSha":{"type":["string","null"]},"supersedesId":{"type":["string","null"],"format":"uuid"},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","docKey","version","title","area","decisionRefs","bodyS3Key","bodySha256","bodyBytes","status","claimedByAgentId","claimExpiresAt","completionPct","shippedAt","implementationCommitSha","supersedesId","createdByAgentId","createdAt","updatedAt"]},"Saga":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"orchestratorServiceId":{"type":"string"},"descriptionS3Key":{"type":"string"},"descriptionSha256":{"type":"string"},"descriptionBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["planned","implemented","deprecated"]},"lockedAt":{"type":["string","null"]},"lockedByAgentId":{"type":["string","null"],"format":"uuid"},"lockedBySliceId":{"type":["string","null"],"format":"uuid"},"reconciliationState":{"type":"string","enum":["clean","dirty"]},"reconciledAt":{"type":["string","null"]},"reconciledByAgentId":{"type":["string","null"],"format":"uuid"},"dirtyReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","orchestratorServiceId","descriptionS3Key","descriptionSha256","descriptionBytes","status","lockedAt","lockedByAgentId","lockedBySliceId","reconciliationState","reconciledAt","reconciledByAgentId","dirtyReason","createdAt","updatedAt"]},"SagaStep":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sagaId":{"type":"string","format":"uuid"},"stepOrder":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"callsServiceId":{"type":"string"},"callsRpc":{"type":"string"},"compensationRpc":{"type":["string","null"]},"sync":{"type":"boolean"},"description":{"type":["string","null"]}},"required":["id","sagaId","stepOrder","callsServiceId","callsRpc","compensationRpc","sync","description"]},"Request":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"requestHash":{"type":"string"},"fromService":{"type":"string"},"toService":{"type":"string"},"kind":{"type":"string"},"specMd":{"type":"string"},"targetArtifactType":{"type":["string","null"]},"targetArtifactId":{"type":["string","null"]},"status":{"type":"string","enum":["open","acknowledged","resolved","rejected"]},"resolvedCommitSha":{"type":["string","null"]},"resolutionMd":{"type":["string","null"]},"relatedDecisionId":{"type":["string","null"]},"shippedVersion":{"type":["string","null"]},"parentRequestId":{"type":["string","null"],"format":"uuid"},"specSummary":{"type":["string","null"]},"requiredCapability":{"type":["string","null"]},"claimedByAgentId":{"type":["string","null"],"format":"uuid"},"claimExpiresAt":{"type":["string","null"]},"expiresAt":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"resolvedByAgentId":{"type":["string","null"],"format":"uuid"},"resolvedAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","requestHash","fromService","toService","kind","specMd","targetArtifactType","targetArtifactId","status","resolvedCommitSha","resolutionMd","relatedDecisionId","shippedVersion","parentRequestId","specSummary","requiredCapability","claimedByAgentId","claimExpiresAt","expiresAt","createdByAgentId","resolvedByAgentId","resolvedAt","createdAt","updatedAt"]},"AuditLog":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"actor":{"type":"string"},"action":{"type":"string"},"targetKind":{"type":"string"},"targetId":{"type":["string","null"]},"payload":{},"truncated":{"type":"boolean"},"requestId":{"type":["string","null"]},"at":{"type":"string"}},"required":["id","actor","action","targetKind","targetId","truncated","requestId","at"]},"CronTick":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"at":{"type":"string"},"payload":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},{"type":"object","additionalProperties":{}},{"type":"array","items":{}},{"type":"null"}]}},"required":["id","name","at","payload"]},"CronTickInsert":{"type":"object","properties":{"name":{"type":"string"},"payload":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},{"type":"object","additionalProperties":{}},{"type":"array","items":{}},{"type":"null"}]}},"required":["name"]},"ReconciledContract":{"type":"object","additionalProperties":{}},"Project":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"projectKey":{"type":"string"},"title":{"type":"string"},"summary":{"type":["string","null"]},"status":{"type":"string","enum":["draft","scope_confirmed","implementing","verifying","complete","abandoned"]},"planS3Key":{"type":["string","null"]},"planSha256":{"type":["string","null"]},"planBytes":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"claimedByAgentId":{"type":["string","null"],"format":"uuid"},"claimExpiresAt":{"type":["string","null"]},"scopeConfirmedAt":{"type":["string","null"]},"scopeConfirmedByAgentId":{"type":["string","null"],"format":"uuid"},"completedAt":{"type":["string","null"]},"completedByAgentId":{"type":["string","null"],"format":"uuid"},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","projectKey","title","summary","status","planS3Key","planSha256","planBytes","claimedByAgentId","claimExpiresAt","scopeConfirmedAt","scopeConfirmedByAgentId","completedAt","completedByAgentId","createdByAgentId","createdAt","updatedAt"]},"ProjectDoctrineCoverage":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"projectId":{"type":"string","format":"uuid"},"doctrineKey":{"type":"string"},"applicability":{"type":"string","enum":["applicable","not-applicable"]},"note":{"type":"string"},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","projectId","doctrineKey","applicability","note","createdByAgentId","createdAt","updatedAt"]},"Slice":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"sliceKey":{"type":"string"},"title":{"type":"string"},"splitConcurrency":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"dagOrder":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["planned","locked","implementing","partially_implemented","implemented","deprecated"]},"lockSemantics":{"type":"string"},"lockedAt":{"type":["string","null"]},"lockedByAgentId":{"type":["string","null"],"format":"uuid"},"claimedByAgentId":{"type":["string","null"],"format":"uuid"},"claimExpiresAt":{"type":["string","null"]},"completionPct":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"descriptionS3Key":{"type":["string","null"]},"descriptionSha256":{"type":["string","null"]},"descriptionBytes":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","sliceKey","title","splitConcurrency","dagOrder","status","lockSemantics","lockedAt","lockedByAgentId","claimedByAgentId","claimExpiresAt","completionPct","descriptionS3Key","descriptionSha256","descriptionBytes","createdByAgentId","createdAt","updatedAt"]},"SliceFeatureDoc":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sliceId":{"type":"string","format":"uuid"},"featureDocId":{"type":"string","format":"uuid"},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"}},"required":["id","sliceId","featureDocId","createdByAgentId","createdAt"]},"SliceFeatureDocEnriched":{"allOf":[{"$ref":"#/components/schemas/SliceFeatureDoc"}],"properties":{"docKey":{"type":["string","null"]},"version":{"type":["integer","null"]},"docStatus":{"type":["string","null"]},"supersedesId":{"type":["string","null"]}},"required":["docKey","version","docStatus","supersedesId"]},"SliceMinimum":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sliceId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["module_fn","module_type","internal_table_cols","constant","rest_surface","event_schema","cli_invocation"]},"name":{"type":"string"},"signatureMd":{"type":["string","null"]},"shapeS3Key":{"type":["string","null"]},"shapeSha256":{"type":["string","null"]},"shapeBytes":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["planned","locked","implemented","deprecated"]},"lockSemantics":{"type":"string"},"lockedAt":{"type":["string","null"]},"lockedByAgentId":{"type":["string","null"],"format":"uuid"},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","sliceId","kind","name","signatureMd","shapeS3Key","shapeSha256","shapeBytes","status","lockSemantics","lockedAt","lockedByAgentId","createdByAgentId","createdAt","updatedAt"]},"SliceBoundaryContract":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"producerSliceId":{"type":"string","format":"uuid"},"consumerSliceId":{"type":["string","null"],"format":"uuid"},"consumerServiceId":{"type":["string","null"]},"refKind":{"type":"string","enum":["artifact","minimum"]},"artifactType":{"type":["string","null"]},"artifactId":{"type":["string","null"],"format":"uuid"},"minimumId":{"type":["string","null"],"format":"uuid"},"status":{"type":"string","enum":["declared","locked","satisfied"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"}},"required":["id","producerSliceId","consumerSliceId","consumerServiceId","refKind","artifactType","artifactId","minimumId","status","createdByAgentId","createdAt"]},"SliceDep":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sliceId":{"type":"string","format":"uuid"},"dependsOnSliceId":{"type":"string","format":"uuid"},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"}},"required":["id","sliceId","dependsOnSliceId","createdByAgentId","createdAt"]},"DbTable":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"name":{"type":"string"},"schemaS3Key":{"type":"string"},"schemaSha256":{"type":"string"},"schemaBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"preseeded":{"type":"boolean"},"description":{"type":["string","null"]},"declaredIn":{"type":["string","null"]},"addedByAgentId":{"type":["string","null"],"format":"uuid"},"status":{"type":"string","enum":["planned","implementing","implemented","deprecated"]},"lockedAt":{"type":["string","null"]},"lockedByAgentId":{"type":["string","null"],"format":"uuid"},"lockedBySliceId":{"type":["string","null"],"format":"uuid"},"reconciliationState":{"type":"string","enum":["clean","dirty"]},"reconciledAt":{"type":["string","null"]},"reconciledByAgentId":{"type":["string","null"],"format":"uuid"},"dirtyReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","name","schemaS3Key","schemaSha256","schemaBytes","preseeded","description","declaredIn","addedByAgentId","status","lockedAt","lockedByAgentId","lockedBySliceId","reconciliationState","reconciledAt","reconciledByAgentId","dirtyReason","createdAt","updatedAt"]},"SqlLookup":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"name":{"type":"string"},"signatureMd":{"type":["string","null"]},"bodyS3Key":{"type":["string","null"]},"bodySha256":{"type":["string","null"]},"bodyBytes":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["planned","implementing","implemented","deprecated"]},"lockSemantics":{"type":"string"},"lockedAt":{"type":["string","null"]},"lockedByAgentId":{"type":["string","null"],"format":"uuid"},"lockedBySliceId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","name","signatureMd","bodyS3Key","bodySha256","bodyBytes","status","lockSemantics","lockedAt","lockedByAgentId","lockedBySliceId","createdAt","updatedAt"]},"RestInterface":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]},"path":{"type":"string"},"requestSchema":{},"responseSchema":{},"agentInvocable":{"type":"boolean"},"operationId":{"type":["string","null"]},"behaviorS3Key":{"type":["string","null"]},"behaviorSha256":{"type":["string","null"]},"behaviorBytes":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["planned","implemented","deprecated"]},"tier":{"type":"string","enum":["tenant-domain","platform-ops"]},"kind":{"type":"string","enum":["standard","alias"]},"aliasTargetId":{"type":["string","null"],"format":"uuid"},"lockedAt":{"type":["string","null"]},"lockedByAgentId":{"type":["string","null"],"format":"uuid"},"lockedBySliceId":{"type":["string","null"],"format":"uuid"},"reconciliationState":{"type":"string","enum":["clean","dirty"]},"reconciledAt":{"type":["string","null"]},"reconciledByAgentId":{"type":["string","null"],"format":"uuid"},"dirtyReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","method","path","agentInvocable","operationId","behaviorS3Key","behaviorSha256","behaviorBytes","status","tier","kind","aliasTargetId","lockedAt","lockedByAgentId","lockedBySliceId","reconciliationState","reconciledAt","reconciledByAgentId","dirtyReason","createdAt","updatedAt"]},"RestInterfaceWithAliasTarget":{"allOf":[{"$ref":"#/components/schemas/RestInterface"}],"properties":{"aliasTarget":{"oneOf":[{"$ref":"#/components/schemas/RestInterfaceAliasTarget"},{"type":"null"}]}},"required":["aliasTarget"]},"RestInterfaceAliasTarget":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]},"path":{"type":"string"},"status":{"type":"string","enum":["planned","implemented","deprecated"]},"tier":{"type":"string","enum":["tenant-domain","platform-ops"]},"operationId":{"type":["string","null"]}},"required":["id","serviceId","method","path","status","tier","operationId"]},"RestInterfaceWithBehavior":{"allOf":[{"$ref":"#/components/schemas/RestInterface"}],"properties":{"behaviorMd":{"type":["string","null"]}},"required":["behaviorMd"]},"GrpcInterface":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"grpcServiceName":{"type":"string"},"rpcName":{"type":"string"},"requestProto":{"type":"string"},"responseProto":{"type":"string"},"agentInvocable":{"type":"boolean"},"sagaCallable":{"type":"boolean"},"operationId":{"type":["string","null"]},"requiredParams":{},"behaviorS3Key":{"type":["string","null"]},"behaviorSha256":{"type":["string","null"]},"behaviorBytes":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["planned","implemented","deprecated"]},"lockedAt":{"type":["string","null"]},"lockedByAgentId":{"type":["string","null"],"format":"uuid"},"lockedBySliceId":{"type":["string","null"],"format":"uuid"},"reconciliationState":{"type":"string","enum":["clean","dirty"]},"reconciledAt":{"type":["string","null"]},"reconciledByAgentId":{"type":["string","null"],"format":"uuid"},"dirtyReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","grpcServiceName","rpcName","requestProto","responseProto","agentInvocable","sagaCallable","operationId","behaviorS3Key","behaviorSha256","behaviorBytes","status","lockedAt","lockedByAgentId","lockedBySliceId","reconciliationState","reconciledAt","reconciledByAgentId","dirtyReason","createdAt","updatedAt"]},"OutboxTopic":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"topicName":{"type":"string"},"payloadSchema":{},"replicationStrategy":{"type":"string","enum":["bullmq","rpc","redis-streams"]},"description":{"type":["string","null"]},"producerLocked":{"type":"boolean"},"lockedAt":{"type":["string","null"]},"lockedByAgentId":{"type":["string","null"],"format":"uuid"},"lockedBySliceId":{"type":["string","null"],"format":"uuid"},"reconciliationState":{"type":"string","enum":["clean","dirty"]},"reconciledAt":{"type":["string","null"]},"reconciledByAgentId":{"type":["string","null"],"format":"uuid"},"dirtyReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","topicName","replicationStrategy","description","producerLocked","lockedAt","lockedByAgentId","lockedBySliceId","reconciliationState","reconciledAt","reconciledByAgentId","dirtyReason","createdAt","updatedAt"]},"OutboxConsumer":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"topicId":{"type":"string","format":"uuid"},"consumerServiceId":{"type":"string"},"handlerDescription":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","topicId","consumerServiceId","handlerDescription","createdAt"]},"ApprovalKind":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"key":{"type":"string"},"label":{"type":"string"},"domain":{"type":"string"},"defaultRoute":{"$ref":"#/components/schemas/ApprovalKindDefaultRoute"},"maxLevels":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"previewSchema":{"oneOf":[{"$ref":"#/components/schemas/ApprovalKindPreviewSchema"},{"type":"null"}]},"deferredAction":{"type":["string","null"]},"outcomes":{"type":"array","items":{"type":"string","enum":["approved","rejected","expired","changes_requested","approved_with_cuts"]}},"venue":{"type":"string","enum":["home","owning_module","either"]},"slaDefault":{"oneOf":[{"$ref":"#/components/schemas/ApprovalKindSla"},{"type":"null"}]},"onTimeoutDefault":{"type":["string","null"],"enum":["escalate_next","keep_open_remind_daily","lapse","none",null]},"permissionKey":{"type":"string"},"entitlementKey":{"type":["string","null"]},"description":{"type":["string","null"]},"status":{"type":"string","enum":["planned","implementing","implemented","deprecated"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"lockedAt":{"type":["string","null"]},"lockedByAgentId":{"type":["string","null"],"format":"uuid"},"lockedBySliceId":{"type":["string","null"],"format":"uuid"},"reconciliationState":{"type":"string","enum":["clean","dirty"]},"reconciledAt":{"type":["string","null"]},"reconciledByAgentId":{"type":["string","null"],"format":"uuid"},"dirtyReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","key","label","domain","defaultRoute","maxLevels","previewSchema","deferredAction","outcomes","venue","slaDefault","onTimeoutDefault","permissionKey","entitlementKey","description","status","createdByAgentId","lockedAt","lockedByAgentId","lockedBySliceId","reconciliationState","reconciledAt","reconciledByAgentId","dirtyReason","createdAt","updatedAt"]},"ApprovalKindDefaultRoute":{"type":"object","properties":{"kind":{"type":"string","const":"org_node_walk"},"levels":{"type":"integer","minimum":1}},"required":["kind"],"additionalProperties":false},"ApprovalKindPreviewSchema":{"type":"object","properties":{"preview_label":{"type":"string","enum":["required","optional","forbidden"]},"preview_subline":{"type":"string","enum":["required","optional","forbidden"]},"counts":{"anyOf":[{"type":"string","enum":["required","optional","forbidden"]},{"type":"object","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"},"additionalProperties":{"type":"string","enum":["required","optional","forbidden"]}}]}},"additionalProperties":false},"ApprovalKindSla":{"type":"object","properties":{"value":{"type":"integer","exclusiveMinimum":0},"unit":{"type":"string","enum":["hour","business_day","working_day"]}},"required":["value","unit"],"additionalProperties":false},"Library":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"repoUrl":{"type":["string","null"]},"version":{"type":"string"},"status":{"type":"string","enum":["planned","active","deprecated"]},"description":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","repoUrl","version","status","description","createdAt","updatedAt"]},"ServiceLibraryDep":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"libraryId":{"type":"string","format":"uuid"},"versionConstraint":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","serviceId","libraryId","versionConstraint","createdAt"]},"LibraryVersion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"libraryId":{"type":"string","format":"uuid"},"version":{"type":"string"},"capabilities":{"type":["string","null"]},"commitSha":{"type":["string","null"]},"publishedAt":{"type":["string","null"]},"releaseNotes":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","libraryId","version","capabilities","commitSha","publishedAt","releaseNotes","createdAt"]},"ServiceEdge":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fromService":{"type":"string"},"toService":{"type":"string"},"kind":{"type":"string","enum":["grpc","rest","outbox","saga"]},"contractRefType":{"type":["string","null"]},"contractRefId":{"type":["string","null"],"format":"uuid"},"status":{"type":"string","enum":["planned","implemented","deprecated"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","fromService","toService","kind","contractRefType","contractRefId","status","createdAt","updatedAt"]},"ChangelogEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"agentId":{"type":["string","null"],"format":"uuid"},"commitSha":{"type":"string"},"summary":{"type":"string"},"bodyMd":{"type":["string","null"]},"prUrl":{"type":["string","null"]},"requestHash":{"type":["string","null"]},"affectedArtifacts":{},"committedAt":{"type":"string"}},"required":["id","serviceId","agentId","commitSha","summary","bodyMd","prUrl","requestHash","committedAt"]},"HealthVerdict":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"verdict":{"type":"string","enum":["good","degraded","bad"]},"reasons":{},"evaluator":{"type":"string"},"evaluatedAt":{"type":"string"}},"required":["id","serviceId","verdict","evaluator","evaluatedAt"]},"DriftEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"severity":{"type":"string","enum":["local","consumer-visible","breaking"]},"summary":{"type":"string"},"bodyMd":{"type":"string"},"status":{"type":"string","enum":["open","accepted-as-canonical","operator-resolved","superseded"]},"relatedDecisionId":{"type":["string","null"]},"relatedArtifactType":{"type":["string","null"]},"relatedArtifactId":{"type":["string","null"]},"projectId":{"type":["string","null"],"format":"uuid"},"discoveredByAgentId":{"type":["string","null"],"format":"uuid"},"resolvedBy":{"type":["string","null"]},"resolutionMd":{"type":["string","null"]},"discoveredAt":{"type":"string"},"resolvedAt":{"type":["string","null"]}},"required":["id","serviceId","severity","summary","bodyMd","status","relatedDecisionId","relatedArtifactType","relatedArtifactId","projectId","discoveredByAgentId","resolvedBy","resolutionMd","discoveredAt","resolvedAt"]},"Pipeline":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["rpc_mutator","rpc_query","http_webhook","worker_cron","worker_lease"]},"trigger":{"type":"string"},"grpcInterfaceId":{"type":["string","null"],"format":"uuid"},"restInterfaceId":{"type":["string","null"],"format":"uuid"},"sagaId":{"type":["string","null"],"format":"uuid"},"sagaStepOrder":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"bodyS3Key":{"type":"string"},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["planned","implemented","deprecated"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","name","kind","trigger","grpcInterfaceId","restInterfaceId","sagaId","sagaStepOrder","bodyS3Key","bodySha256","bodyBytes","status","createdByAgentId","createdAt","updatedAt"]},"DoctrineException":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"doctrinePath":{"type":"string"},"filedAgainstDoctrineRevision":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"scope":{"type":"string"},"rationaleS3Key":{"type":"string"},"rationaleSha256":{"type":"string"},"rationaleBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"decisionId":{"type":["string","null"]},"status":{"type":"string","enum":["active","sunset_planned","revoked"]},"sunsetTargetDate":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","doctrinePath","filedAgainstDoctrineRevision","scope","rationaleS3Key","rationaleSha256","rationaleBytes","decisionId","status","sunsetTargetDate","createdByAgentId","createdAt","updatedAt"]},"Runbook":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["local_dev","operations","incident","key_management","compliance","release"]},"repoRelativePath":{"type":"string"},"summaryS3Key":{"type":"string"},"summarySha256":{"type":"string"},"summaryBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["active","stale","superseded"]},"lastVerifiedAt":{"type":["string","null"]},"supersededById":{"type":["string","null"],"format":"uuid"},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","title","kind","repoRelativePath","summaryS3Key","summarySha256","summaryBytes","status","lastVerifiedAt","supersededById","createdByAgentId","createdAt","updatedAt"]},"OpenQuestion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":["string","null"]},"module":{"type":["string","null"]},"questionMd":{"type":"string"},"contextS3Key":{"type":["string","null"]},"contextSha256":{"type":["string","null"]},"contextBytes":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["open","in_discussion","answered","obsolete"]},"answeredByDecisionId":{"type":["string","null"]},"answeredByAnswerId":{"type":["string","null"],"format":"uuid"},"raisedByAgentId":{"type":["string","null"],"format":"uuid"},"topicTags":{"type":"array","items":{"type":"string"}},"priority":{"type":"string","enum":["low","medium","high","blocker"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","module","questionMd","contextS3Key","contextSha256","contextBytes","status","answeredByDecisionId","answeredByAnswerId","raisedByAgentId","topicTags","priority","createdAt","updatedAt"]},"Runner":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["agent-runner","orchestrator"]},"serviceId":{"type":["string","null"]},"baseUrl":{"type":"string"},"version":{"type":["string","null"]},"status":{"type":"string","enum":["online","degraded","offline"]},"lastHeartbeatAt":{"type":"string"},"registeredByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","kind","serviceId","baseUrl","version","status","lastHeartbeatAt","registeredByAgentId","createdAt","updatedAt"]},"RunnerRegister":{"type":"object","properties":{"kind":{"type":"string","enum":["agent-runner","orchestrator"]},"serviceId":{"type":["string","null"]},"baseUrl":{"type":"string","format":"uri","pattern":"^https?:\\/\\/"},"version":{"type":["string","null"]},"status":{"type":"string","enum":["online","degraded","offline"]}},"required":["kind","baseUrl"]},"UsageCeiling":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"runnerId":{"type":"string","format":"uuid"},"ceiling":{"type":"string","enum":["subscription","api_credit"]},"state":{"type":"string","enum":["ok","warning","exhausted"]},"resetsAt":{"type":["string","null"]},"counters":{},"observedAt":{"type":"string"}},"required":["id","runnerId","ceiling","state","resetsAt","observedAt"]},"RunnerUsageReport":{"type":"object","properties":{"ceiling":{"type":"string","enum":["subscription","api_credit"]},"state":{"type":"string","enum":["ok","warning","exhausted"]},"resetsAt":{"type":["string","null"],"format":"date-time"},"counters":{}},"required":["ceiling","state"]},"RoutingHit":{"type":"object","properties":{"serviceId":{"type":"string"},"sliceId":{"type":"string"},"runnerBaseUrl":{"type":"string"},"runnerStatus":{"type":"string","enum":["online","degraded","offline"]},"agentId":{"type":"string"}},"required":["serviceId","runnerBaseUrl","runnerStatus"]},"UsageFanInRunner":{"type":"object","properties":{"runnerId":{"type":"string","format":"uuid"},"serviceId":{"type":["string","null"]},"kind":{"type":"string","enum":["agent-runner","orchestrator"]},"baseUrl":{"type":"string"},"runnerStatus":{"type":"string","enum":["online","degraded","offline"]},"ceilings":{"type":"array","items":{"type":"object","properties":{"ceiling":{"type":"string","enum":["subscription","api_credit"]},"state":{"type":"string","enum":["ok","warning","exhausted"]},"resetsAt":{"type":["string","null"],"format":"date-time"},"observedAt":{"type":"string","format":"date-time"}},"required":["ceiling","state","resetsAt","observedAt"]}}},"required":["runnerId","serviceId","kind","baseUrl","runnerStatus","ceilings"]},"NotificationType":{"type":"object","properties":{"typeKey":{"type":"string"},"meaning":{"type":"string"},"examples":{"type":"string"},"notFor":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["typeKey","meaning","examples","notFor","createdAt","updatedAt"]},"NotificationEvent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"eventKey":{"type":"string"},"version":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"supersedesId":{"type":["string","null"],"format":"uuid"},"status":{"type":"string","enum":["proposed","approved","built","retired"]},"typeKey":{"type":"string"},"groupLabel":{"type":["string","null"]},"message":{"type":"string"},"audience":{"type":"string","enum":["customers","tenant_staff","nodii_staff","other"]},"audienceDetail":{"type":["string","null"]},"channels":{"type":"array","items":{"type":"string"}},"muteClass":{"type":["string","null"],"enum":["mutable","protected","account_email","test",null]},"billing":{"type":["string","null"],"enum":["billed","free","by_recipient",null]},"emailRoute":{"type":["string","null"],"enum":["nodii_only","prefer_tenant","prefer_tenant_guarded","none","provider_under_test",null]},"payloadSchema":{},"producerServiceIds":{"type":"array","items":{"type":"string"}},"templateKeys":{"type":["object","null"],"additionalProperties":{"type":"string"}},"builtCommitSha":{"type":["string","null"]},"replaces":{"type":"array","items":{"type":"string"}},"replacedBy":{"type":"array","items":{"type":"string"}},"decisionRefs":{"type":"array","items":{"type":"string"}},"notes":{"type":["string","null"]},"retireReason":{"type":["string","null"]},"proposedByServiceId":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","eventKey","version","supersedesId","status","typeKey","groupLabel","message","audience","audienceDetail","channels","muteClass","billing","emailRoute","producerServiceIds","templateKeys","builtCommitSha","replaces","replacedBy","decisionRefs","notes","retireReason","proposedByServiceId","createdByAgentId","createdAt","updatedAt"]},"NotificationEventPropose":{"type":"object","properties":{"eventKey":{"type":"string","minLength":1,"maxLength":200},"typeKey":{"type":"string","minLength":1,"maxLength":100},"groupLabel":{"type":["string","null"],"maxLength":2000},"message":{"type":"string","minLength":1,"maxLength":4000},"audience":{"type":"string","enum":["customers","tenant_staff","nodii_staff","other"]},"audienceDetail":{"type":["string","null"],"maxLength":2000},"channels":{"type":"array","items":{"type":"string","enum":["email","sms","whatsapp","voice","push","in_app","oob"]},"minItems":1,"maxItems":7},"muteClass":{"type":["string","null"],"enum":["mutable","protected","account_email","test",null]},"billing":{"type":["string","null"],"enum":["billed","free","by_recipient",null]},"emailRoute":{"type":["string","null"],"enum":["nodii_only","prefer_tenant","prefer_tenant_guarded","none","provider_under_test",null]},"payloadSchema":{"type":["object","null"],"additionalProperties":{}},"producerServiceIds":{"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"minItems":1,"maxItems":50},"replaces":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":100},"decisionRefs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50},"maxItems":100},"notes":{"type":["string","null"],"maxLength":8000}},"required":["eventKey","typeKey","message","audience","channels","producerServiceIds"],"additionalProperties":false},"NotificationEventRevise":{"type":"object","properties":{"typeKey":{"type":"string","minLength":1,"maxLength":100},"groupLabel":{"type":["string","null"],"maxLength":2000},"message":{"type":"string","minLength":1,"maxLength":4000},"audience":{"type":"string","enum":["customers","tenant_staff","nodii_staff","other"]},"audienceDetail":{"type":["string","null"],"maxLength":2000},"channels":{"type":"array","items":{"type":"string","enum":["email","sms","whatsapp","voice","push","in_app","oob"]},"minItems":1,"maxItems":7},"muteClass":{"type":["string","null"],"enum":["mutable","protected","account_email","test",null]},"billing":{"type":["string","null"],"enum":["billed","free","by_recipient",null]},"emailRoute":{"type":["string","null"],"enum":["nodii_only","prefer_tenant","prefer_tenant_guarded","none","provider_under_test",null]},"payloadSchema":{"type":["object","null"],"additionalProperties":{}},"producerServiceIds":{"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"minItems":1,"maxItems":50},"replaces":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":100},"decisionRefs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50},"maxItems":100},"notes":{"type":["string","null"],"maxLength":8000}},"additionalProperties":false},"NotificationEventApprove":{"type":"object","properties":{"muteClass":{"type":"string","enum":["mutable","protected","account_email","test"]},"billing":{"type":"string","enum":["billed","free","by_recipient"]},"emailRoute":{"type":"string","enum":["nodii_only","prefer_tenant","prefer_tenant_guarded","none","provider_under_test"]},"payloadSchema":{"type":["object","null"],"additionalProperties":{}},"notes":{"type":["string","null"],"maxLength":8000}},"required":["muteClass","billing","emailRoute"],"additionalProperties":false},"NotificationEventMarkBuilt":{"type":"object","properties":{"templateKeys":{"type":"object","properties":{"email":{"type":"string","minLength":1,"maxLength":200},"sms":{"type":"string","minLength":1,"maxLength":200},"whatsapp":{"type":"string","minLength":1,"maxLength":200},"voice":{"type":"string","minLength":1,"maxLength":200},"push":{"type":"string","minLength":1,"maxLength":200},"in_app":{"type":"string","minLength":1,"maxLength":200},"oob":{"type":"string","minLength":1,"maxLength":200}},"additionalProperties":false},"commitSha":{"type":"string","pattern":"^[0-9a-f]{7,40}$"}},"required":["templateKeys","commitSha"],"additionalProperties":false},"NotificationEventRetire":{"type":"object","properties":{"replacedBy":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":50},"reason":{"type":"string","maxLength":2000}},"additionalProperties":false},"Worker":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"workerKey":{"type":"string"},"kind":{"type":"string","enum":["cron","sweeper","consumer","saga-runner","outbox-drainer","queue-worker","reconciler","other"]},"description":{"type":["string","null"]},"cadence":{"type":["string","null"]},"cadenceSeconds":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"sourcePath":{"type":["string","null"]},"entrypoints":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["planned","implementing","partially_implemented","implemented","deprecated"]},"idempotent":{"type":["boolean","null"]},"tenancy":{"type":["string","null"],"enum":["per-tenant","global",null]},"concurrencyGuard":{"type":["string","null"],"enum":["none","lease","advisory-lock","consumer-group","queue","row-lock",null]},"processIsolation":{"type":"string","enum":["compliant","non_compliant","unknown"]},"isolationEvidence":{"type":["string","null"]},"deployedAs":{"type":["string","null"]},"contractRefs":{"type":"array","items":{"type":"string"}},"ackBehavior":{"type":["string","null"]},"retryBackoff":{"type":["string","null"]},"ratification":{"type":"string","enum":["unratified","ratified","disputed"]},"ratifiedAt":{"type":["string","null"]},"ratifiedByAgentId":{"type":["string","null"],"format":"uuid"},"ratificationNote":{"type":["string","null"]},"provenance":{"type":"string","enum":["hub-scan","service"]},"scannedCommitSha":{"type":["string","null"]},"decisionRefs":{"type":"array","items":{"type":"string"}},"addedByAgentId":{"type":["string","null"],"format":"uuid"},"reconciliationState":{"type":"string","enum":["clean","dirty"]},"reconciledAt":{"type":["string","null"]},"reconciledByAgentId":{"type":["string","null"],"format":"uuid"},"dirtyReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","workerKey","kind","description","cadence","cadenceSeconds","sourcePath","entrypoints","status","idempotent","tenancy","concurrencyGuard","processIsolation","isolationEvidence","deployedAs","contractRefs","ackBehavior","retryBackoff","ratification","ratifiedAt","ratifiedByAgentId","ratificationNote","provenance","scannedCommitSha","decisionRefs","addedByAgentId","reconciliationState","reconciledAt","reconciledByAgentId","dirtyReason","createdAt","updatedAt"]},"WorkerServiceSummary":{"type":"object","properties":{"serviceId":{"type":"string"},"total":{"type":"integer"},"compliant":{"type":"integer"},"non_compliant":{"type":"integer"},"unknown":{"type":"integer"},"unratified":{"type":"integer"},"ratified":{"type":"integer"},"disputed":{"type":"integer"}},"required":["serviceId","total","compliant","non_compliant","unknown","unratified","ratified","disputed"]},"WorkerCreate":{"type":"object","properties":{"workerKey":{"type":"string","minLength":1,"maxLength":200},"kind":{"type":"string","enum":["cron","sweeper","consumer","saga-runner","outbox-drainer","queue-worker","reconciler","other"]},"status":{"type":"string","enum":["planned","implementing","partially_implemented","implemented","deprecated"]},"description":{"type":["string","null"],"maxLength":4000},"cadence":{"type":["string","null"],"maxLength":200},"cadenceSeconds":{"type":["integer","null"],"exclusiveMinimum":0},"sourcePath":{"type":["string","null"],"maxLength":500},"entrypoints":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500},"maxItems":50},"idempotent":{"type":["boolean","null"]},"tenancy":{"type":["string","null"],"enum":["per-tenant","global",null]},"concurrencyGuard":{"type":["string","null"],"enum":["none","lease","advisory-lock","consumer-group","queue","row-lock",null]},"processIsolation":{"type":"string","enum":["compliant","non_compliant","unknown"]},"isolationEvidence":{"type":["string","null"],"maxLength":4000},"deployedAs":{"type":["string","null"],"maxLength":500},"contractRefs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":100},"ackBehavior":{"type":["string","null"],"maxLength":4000},"retryBackoff":{"type":["string","null"],"maxLength":4000},"decisionRefs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50},"maxItems":100}},"required":["workerKey","kind"],"additionalProperties":false},"WorkerPreseedResult":{"type":"object","properties":{"inserted":{"type":"integer"},"updated":{"type":"integer"},"skipped":{"type":"integer"},"conflicts":{"type":"array","items":{"type":"object","properties":{"workerKey":{"type":"string"},"existingServiceId":{"type":"string"}},"required":["workerKey","existingServiceId"]}}},"required":["inserted","updated","skipped","conflicts"]},"WorkerPreseed":{"type":"object","properties":{"scannedCommitSha":{"type":"string","pattern":"^[0-9a-f]{7,40}$"},"workers":{"type":"array","items":{"$ref":"#/components/schemas/WorkerCreate"},"minItems":1,"maxItems":500}},"required":["workers"],"additionalProperties":false},"WorkerPatch":{"type":"object","properties":{"kind":{"type":"string","enum":["cron","sweeper","consumer","saga-runner","outbox-drainer","queue-worker","reconciler","other"]},"description":{"type":["string","null"],"maxLength":4000},"cadence":{"type":["string","null"],"maxLength":200},"cadenceSeconds":{"type":["integer","null"],"exclusiveMinimum":0},"sourcePath":{"type":["string","null"],"maxLength":500},"entrypoints":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500},"maxItems":50},"idempotent":{"type":["boolean","null"]},"tenancy":{"type":["string","null"],"enum":["per-tenant","global",null]},"concurrencyGuard":{"type":["string","null"],"enum":["none","lease","advisory-lock","consumer-group","queue","row-lock",null]},"processIsolation":{"type":"string","enum":["compliant","non_compliant","unknown"]},"isolationEvidence":{"type":["string","null"],"maxLength":4000},"deployedAs":{"type":["string","null"],"maxLength":500},"contractRefs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":100},"ackBehavior":{"type":["string","null"],"maxLength":4000},"retryBackoff":{"type":["string","null"],"maxLength":4000},"decisionRefs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50},"maxItems":100}},"additionalProperties":false},"WorkerDispute":{"type":"object","properties":{"reason":{"type":"string","minLength":10,"maxLength":4000},"corrections":{"type":"object","additionalProperties":{}}},"required":["reason"],"additionalProperties":false},"Issue":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"serviceId":{"type":"string"},"title":{"type":"string"},"bodyS3Key":{"type":["string","null"]},"bodySha256":{"type":["string","null"]},"bodyBytes":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"kind":{"type":"string","enum":["feature","bug","chore","drift","request","verification"]},"status":{"type":"string","enum":["todo","in_progress","in_review","blocked","done","wont_do"]},"priority":{"type":"string","enum":["p0","p1","p2","p3"]},"project":{"type":["string","null"]},"source":{"type":"string","enum":["manual","backlog_import","drift","request","ticket"]},"sourceRef":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{}},"claimedByAgentId":{"type":["string","null"],"format":"uuid"},"claimedOnBehalfOf":{"type":["string","null"]},"claimExpiresAt":{"type":["string","null"]},"links":{"$ref":"#/components/schemas/IssueLinks"},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"closedAt":{"type":["string","null"]}},"required":["id","key","serviceId","title","bodyS3Key","bodySha256","bodyBytes","kind","status","priority","project","source","sourceRef","metadata","claimedByAgentId","claimedOnBehalfOf","claimExpiresAt","links","createdByAgentId","createdAt","updatedAt","closedAt"]},"IssueLinks":{"type":"object","properties":{"prs":{"type":"array","items":{"type":"string"},"default":[]},"changes":{"type":"array","items":{"type":"string"},"default":[]},"builds":{"type":"array","items":{"type":"string"},"default":[]},"decisions":{"type":"array","items":{"type":"string"},"default":[]}},"required":["prs","changes","builds","decisions"]},"IssueDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"serviceId":{"type":"string"},"title":{"type":"string"},"bodyS3Key":{"type":["string","null"]},"bodySha256":{"type":["string","null"]},"bodyBytes":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"kind":{"type":"string","enum":["feature","bug","chore","drift","request","verification"]},"status":{"type":"string","enum":["todo","in_progress","in_review","blocked","done","wont_do"]},"priority":{"type":"string","enum":["p0","p1","p2","p3"]},"project":{"type":["string","null"]},"source":{"type":"string","enum":["manual","backlog_import","drift","request","ticket"]},"sourceRef":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{}},"claimedByAgentId":{"type":["string","null"],"format":"uuid"},"claimedOnBehalfOf":{"type":["string","null"]},"claimExpiresAt":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"closedAt":{"type":["string","null"]},"links":{"type":"object","properties":{"prs":{"type":"array","items":{"type":"string"},"default":[]},"changes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":["string","null"]}},"required":["id","title"]}},"builds":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":["string","null"]}},"required":["id","title"]}},"decisions":{"type":"array","items":{"type":"string"},"default":[]}},"required":["prs","changes","builds","decisions"]},"bodyMd":{"type":["string","null"]},"events":{"type":"array","items":{"$ref":"#/components/schemas/IssueEvent"}},"transitions":{"type":"array","items":{"type":"string","enum":["todo","in_progress","in_review","blocked","done","wont_do"]}},"leaseLive":{"type":"boolean"},"laneIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["id","key","serviceId","title","bodyS3Key","bodySha256","bodyBytes","kind","status","priority","project","source","sourceRef","metadata","claimedByAgentId","claimedOnBehalfOf","claimExpiresAt","createdByAgentId","createdAt","updatedAt","closedAt","links","bodyMd","events","transitions","leaseLive","laneIds"]},"IssueEvent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"issueId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["created","updated","status_changed","claimed","claim_renewed","released","claim_expired","commented","backlog_added","backlog_moved","backlog_removed","imported"]},"actorAgentId":{"type":["string","null"],"format":"uuid"},"actorLabel":{"type":["string","null"]},"fromStatus":{"type":["string","null"],"enum":["todo","in_progress","in_review","blocked","done","wont_do",null]},"toStatus":{"type":["string","null"],"enum":["todo","in_progress","in_review","blocked","done","wont_do",null]},"note":{"type":["string","null"]},"data":{"type":"object","additionalProperties":{}},"createdAt":{"type":"string"}},"required":["id","issueId","kind","actorAgentId","actorLabel","fromStatus","toStatus","note","data","createdAt"]},"Backlog":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"serviceId":{"type":["string","null"]},"project":{"type":["string","null"]},"description":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","slug","name","serviceId","project","description","createdByAgentId","createdAt","updatedAt"]},"BacklogDetail":{"allOf":[{"$ref":"#/components/schemas/Backlog"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BacklogEntry"}}},"required":["items"]},"BacklogEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["todo","in_progress","in_review","blocked","done","wont_do"]},"priority":{"type":"string","enum":["p0","p1","p2","p3"]},"kind":{"type":"string","enum":["feature","bug","chore","drift","request","verification"]},"serviceId":{"type":"string"},"project":{"type":["string","null"]},"claimedByAgentId":{"type":["string","null"]},"claimedOnBehalfOf":{"type":["string","null"]},"claimExpiresAt":{"type":["string","null"]},"position":{"type":"number"},"addedAt":{"type":"string"}},"required":["id","key","title","status","priority","kind","serviceId","project","claimedByAgentId","claimedOnBehalfOf","claimExpiresAt","position","addedAt"]},"ServiceWorkSummary":{"type":"object","properties":{"serviceId":{"type":"string"},"openTotal":{"type":"integer"},"openByStatus":{"type":"object","properties":{"todo":{"type":"integer"},"in_progress":{"type":"integer"},"in_review":{"type":"integer"},"blocked":{"type":"integer"}},"required":["todo","in_progress","in_review","blocked"]},"claimedNow":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["todo","in_progress","in_review","blocked","done","wont_do"]},"claimedByAgentId":{"type":["string","null"]},"claimedOnBehalfOf":{"type":["string","null"]},"claimExpiresAt":{"type":["string","null"]}},"required":["id","key","title","status","claimedByAgentId","claimedOnBehalfOf","claimExpiresAt"]}},"oldestOpen":{"type":["object","null"],"properties":{"id":{"type":"string"},"key":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["todo","in_progress","in_review","blocked","done","wont_do"]},"createdAt":{"type":"string"}},"required":["id","key","title","status","createdAt"]}},"required":["serviceId","openTotal","openByStatus","claimedNow","oldestOpen"]},"Build":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"repo":{"type":"string"},"environment":{"type":"string","enum":["dev","uat","prod"]},"workflowPath":{"type":["string","null"]},"commitSha":{"type":"string"},"imageDigest":{"type":["string","null"]},"prNumber":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"ciStatus":{"type":"string","enum":["unknown","pending","success","bypassed","failure","cancelled"]},"deployStatus":{"type":"string","enum":["queued","in_progress","success","failure","cancelled"]},"runId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"runUrl":{"type":"string"},"startedAt":{"type":"string"},"completedAt":{"type":["string","null"]},"source":{"type":"string","enum":["github_actions_poll","deploy_report"]},"changesBaseSha":{"type":["string","null"]},"changesComputedAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","repo","environment","workflowPath","commitSha","imageDigest","prNumber","ciStatus","deployStatus","runId","runUrl","startedAt","completedAt","source","changesBaseSha","changesComputedAt","createdAt","updatedAt"]},"BuildView":{"allOf":[{"$ref":"#/components/schemas/Build"}],"properties":{"blocked":{"type":"boolean"}},"required":["blocked"]},"BuildSummary":{"type":"object","properties":{"serviceId":{"type":"string"},"environment":{"type":"string","enum":["dev","uat","prod"]},"latestBuild":{"$ref":"#/components/schemas/Build"},"countsByCiStatus":{"type":"object","properties":{"unknown":{"type":"integer"},"pending":{"type":"integer"},"success":{"type":"integer"},"bypassed":{"type":"integer"},"failure":{"type":"integer"},"cancelled":{"type":"integer"}},"required":["unknown","pending","success","bypassed","failure","cancelled"]},"countsByDeployStatus":{"type":"object","properties":{"queued":{"type":"integer"},"in_progress":{"type":"integer"},"success":{"type":"integer"},"failure":{"type":"integer"},"cancelled":{"type":"integer"}},"required":["queued","in_progress","success","failure","cancelled"]}},"required":["serviceId","environment","latestBuild","countsByCiStatus","countsByDeployStatus"]},"BuildDetail":{"allOf":[{"$ref":"#/components/schemas/BuildView"}],"properties":{"blockingChangeIds":{"type":"array","items":{"type":"string","format":"uuid"}},"changes":{"type":"array","items":{"$ref":"#/components/schemas/Change"}}},"required":["blockingChangeIds","changes"]},"Change":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"repo":{"type":"string"},"prNumber":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"title":{"type":"string"},"prUrl":{"type":"string"},"baseBranch":{"type":"string"},"mergedAt":{"type":"string"},"mergedBy":{"type":["string","null"]},"mergeCommitSha":{"type":"string"},"changelogEntryId":{"type":["string","null"],"format":"uuid"},"mark":{"type":"string","enum":["unverified","verified","broken","rolled_back"]},"markReason":{"type":["string","null"]},"markedByAgentId":{"type":["string","null"],"format":"uuid"},"markedAt":{"type":["string","null"]},"fixedByChangeId":{"type":["string","null"],"format":"uuid"},"touches":{"type":"array","items":{"type":"string"}},"userVisible":{"type":"boolean"},"userVisibleOverridden":{"type":"boolean"},"filesFetchedAt":{"type":["string","null"]},"filesTruncated":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","repo","prNumber","title","prUrl","baseBranch","mergedAt","mergedBy","mergeCommitSha","changelogEntryId","mark","markReason","markedByAgentId","markedAt","fixedByChangeId","touches","userVisible","userVisibleOverridden","filesFetchedAt","filesTruncated","createdAt","updatedAt"]},"BuildReport":{"type":"object","properties":{"serviceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"environment":{"type":"string","enum":["dev","uat","prod"]},"commitSha":{"type":"string","pattern":"^[0-9a-f]{40}$"},"runUrl":{"type":"string","pattern":"^https:\\/\\/github\\.com\\/([A-Za-z0-9_.-]+\\/[A-Za-z0-9_.-]+)\\/actions\\/runs\\/(\\d+)(?:\\/.*)?$"},"repo":{"type":"string","pattern":"^[A-Za-z0-9_.-]+\\/[A-Za-z0-9_.-]+$"},"runId":{"type":"integer","exclusiveMinimum":0},"imageDigest":{"type":["string","null"],"pattern":"^sha256:[0-9a-f]{64}$"},"prNumber":{"type":["integer","null"],"exclusiveMinimum":0},"conclusion":{"type":"string","enum":["queued","in_progress","success","failure","cancelled"]},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}},"required":["serviceId","environment","commitSha","runUrl","conclusion"]},"ChangeView":{"allOf":[{"$ref":"#/components/schemas/Change"}],"properties":{"changelogSummary":{"type":["string","null"]}},"required":["changelogSummary"]},"ChangeDetail":{"allOf":[{"$ref":"#/components/schemas/ChangeView"}],"properties":{"builds":{"type":"array","items":{"$ref":"#/components/schemas/Build"}},"files":{"type":"array","items":{"$ref":"#/components/schemas/ChangeFile"}}},"required":["builds","files"]},"ChangeFile":{"type":"object","properties":{"path":{"type":"string"},"status":{"type":"string"},"additions":{"type":"integer"},"deletions":{"type":"integer"},"previousPath":{"type":["string","null"]}},"required":["path","status","additions","deletions","previousPath"]},"ChangeMarkInput":{"type":"object","properties":{"mark":{"type":"string","enum":["unverified","verified","broken","rolled_back"]},"reason":{"type":["string","null"],"maxLength":4000},"fixedByChangeId":{"type":["string","null"],"format":"uuid"},"userVisible":{"type":"boolean"}}},"ServiceDelivery":{"type":"object","properties":{"serviceId":{"type":"string"},"lastBuilds":{"type":"array","items":{"$ref":"#/components/schemas/BuildView"}},"changes":{"type":"object","properties":{"unverified":{"type":"integer"},"verified":{"type":"integer"},"broken":{"type":"integer"},"rolled_back":{"type":"integer"}},"required":["unverified","verified","broken","rolled_back"]}},"required":["serviceId","lastBuilds","changes"]},"DeliveryPollState":{"type":"object","properties":{"repo":{"type":"string"},"serviceId":{"type":"string"},"defaultBranch":{"type":["string","null"]},"prHwm":{"type":["string","null"]},"runHwm":{"type":["string","null"]},"deployWorkflows":{},"ciWorkflows":{},"workflowsDiscoveredAt":{"type":["string","null"]},"lastPolledAt":{"type":["string","null"]},"lastSuccessAt":{"type":["string","null"]},"lastError":{"type":["string","null"]},"consecutiveFailures":{"type":"integer"},"updatedAt":{"type":"string"}},"required":["repo","serviceId","defaultBranch","prHwm","runHwm","workflowsDiscoveredAt","lastPolledAt","lastSuccessAt","lastError","consecutiveFailures","updatedAt"]},"DeployObservation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":["string","null"]},"serviceRepo":{"type":"string"},"environment":{"type":"string","enum":["dev","uat","prod"]},"cluster":{"type":"string"},"deployable":{"type":"string"},"taskDefinitionArn":{"type":"string"},"image":{"type":"string"},"imageDigest":{"type":"string"},"commitSha":{"type":"string"},"desiredCount":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"runningCount":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"rolloutState":{"type":"string","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"deployedAt":{"type":"string"},"observedAt":{"type":"string"},"workflowRunUrl":{"type":"string"},"actor":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","serviceId","serviceRepo","environment","cluster","deployable","taskDefinitionArn","image","imageDigest","commitSha","desiredCount","runningCount","rolloutState","deployedAt","observedAt","workflowRunUrl","actor","createdAt"]},"DeployReportInput":{"type":"object","properties":{"service_repo":{"type":"string","pattern":"^cognion-nucleus\\/[A-Za-z0-9._-]+$"},"env":{"type":"string","const":"dev"},"cluster":{"type":"string","minLength":1},"deployable":{"type":"string","minLength":1},"task_definition_arn":{"type":"string","minLength":1},"image":{"type":"string","minLength":1},"image_digest":{"type":"string","pattern":"^sha256:[a-fA-F0-9]{64}$"},"commit_sha":{"type":"string","pattern":"^[a-fA-F0-9]{40}$"},"desired_count":{"type":"integer","minimum":0},"running_count":{"type":"integer","minimum":0},"rollout_state":{"type":"string","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"deployed_at":{"type":"string","format":"date-time"},"observed_at":{"type":"string","format":"date-time"},"workflow_run_url":{"type":"string","format":"uri"},"actor":{"type":"string","minLength":1}},"required":["service_repo","env","cluster","deployable","task_definition_arn","image","image_digest","commit_sha","desired_count","running_count","rollout_state","deployed_at","observed_at","workflow_run_url","actor"],"additionalProperties":false},"RuntimeObservation":{"allOf":[{"$ref":"#/components/schemas/DeployObservation"}],"properties":{"stalenessSeconds":{"type":"integer","minimum":0},"build":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"runUrl":{"type":"string","format":"uri"},"deployStatus":{"type":"string"}},"required":["id","runUrl","deployStatus"]}},"required":["stalenessSeconds","build"]},"Machine":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"hostFacts":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"coordinatorAgentId":{"type":"string","format":"uuid"},"heavySlotTotal":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"memoryFacts":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"lastReportAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","hostFacts","coordinatorAgentId","heavySlotTotal","memoryFacts","lastReportAt","createdAt","updatedAt"]},"FleetGateResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"gatedServiceCount":{"type":"integer","minimum":0},"totals":{"type":"object","properties":{"drift":{"type":"integer","minimum":0},"request":{"type":"integer","minimum":0},"question":{"type":"integer","minimum":0},"all":{"type":"integer","minimum":0}},"required":["drift","request","question","all"]},"services":{"type":"array","items":{"type":"object","properties":{"serviceId":{"type":"string"},"total":{"type":"integer","minimum":0},"byKind":{"type":"object","properties":{"drift":{"type":"integer","minimum":0},"request":{"type":"integer","minimum":0},"question":{"type":"integer","minimum":0}},"required":["drift","request","question"]},"oldest":{"type":"object","properties":{"kind":{"type":"string","enum":["drift","request","question","lane_escalation"]},"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"ageSeconds":{"type":"integer","minimum":0}},"required":["kind","id","title","createdAt","ageSeconds"]}},"required":["serviceId","total","byKind","oldest"]}},"computedAt":{"type":"string","format":"date-time"}},"required":["gatedServiceCount","totals","services","computedAt"]}},"required":["data"]}}},"paths":{"/api/v1/health":{"get":{"responses":{"200":{"description":"Service is alive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}},"operationId":"getHealth","tags":["Health"],"parameters":[],"summary":"Health probe","description":"Open endpoint. Returns 200 if the process is alive, with the state of the devops permission catalog publish. No DB probe — use /health/db for that."}},"/api/v1/services":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Service"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServices","tags":["Services"],"parameters":[],"summary":"List all services","description":"Returns every service in the platform, ordered by migration wave then id."},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Service"}},"required":["data"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createService","tags":["Services"],"parameters":[],"summary":"Register a new service","description":"Idempotent — calling with an existing id returns the existing row (use PATCH for explicit updates).","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceInsert"}}}}}},"/api/v1/services/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Service"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getService","tags":["Services"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Get a service by id"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Service"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateService","tags":["Services"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Update a service","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"name":{"type":"string"},"wave":{"type":"integer","minimum":0,"maximum":5},"status":{"type":"string","enum":["planned","feature_docs_drafting","contracts_authoring","scaffolding","implementing","partially_implemented","implemented","live","active","deprecated","frozen"]},"owner":{"type":["string","null"]},"repoUrl":{"type":["string","null"]},"description":{"type":["string","null"]},"activeImplementerAgentId":{"type":["string","null"],"format":"uuid"},"lastImplSessionAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}}}}}}}},"/api/v1/services/{id}/mark-implementing":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Service"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"markServiceImplementing","tags":["Services"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Mark a service as actively being implemented by an agent","description":"Sets active_implementer_agent_id + bumps last_impl_session_at. Promotes status forward to 'implementing' if currently in a pre-impl phase. Idempotent — same agent calling repeatedly only bumps the timestamp.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"}},"required":["agentId"]}}}}}},"/api/v1/services/{id}/clear-implementer":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Service"}},"required":["data"]}}}},"404":{"description":"Not found or expectedAgentId mismatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"clearServiceImplementer","tags":["Services"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Clear the active implementer pointer for a service","description":"If expectedAgentId is provided, only clears when the current pointer matches (used by the pruner to avoid clobbering a fresh session). Returns 404 if the service doesn't exist OR if expectedAgentId didn't match.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"expectedAgentId":{"type":"string","format":"uuid"}}}}}}}},"/api/v1/services/{id}/recompute-status":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Service"},"facts":{"$ref":"#/components/schemas/ServiceStatusFacts"}},"required":["data","facts"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"recomputeServiceStatus","tags":["Services"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Recompute a service's status from authoritative Dev state","description":"Promotion ladder: planned → feature_docs_drafting → contracts_authoring → implementing → partially_implemented → implemented. Skips terminal states (live, deprecated, frozen) and legacy states (active, scaffolding) — operator-only territory."}},"/api/v1/agents":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Agent"}],"properties":{"personDisplayName":{"type":"object","properties":{"value":{"type":["string","null"]},"masked":{"type":"boolean"},"hint":{"type":["string","null"]}},"required":["value","masked","hint"]}},"required":["personDisplayName"]}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listAgents","tags":["Agents"],"parameters":[],"summary":"List all agents","description":"Ordered by last_seen_at desc; includes heartbeatIntervalSeconds and authenticationMethod."},"post":{"responses":{"201":{"description":"Registered (created or refreshed)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Agent"}},"required":["data"]}}}}},"operationId":"registerAgent","tags":["Agents"],"parameters":[],"summary":"Register a new agent session","description":"Idempotent on session_id — re-registering with the same session returns the existing row with status flipped to active.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRegister"}}}}}},"/api/v1/agents/{id}/lane-limit":{"put":{"responses":{"200":{"description":"OK"}},"operationId":"setAgentLaneLimit","tags":["Agents"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Set an agent lane limit as its coordinator or operator","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"laneLimit":{"type":"integer","minimum":1,"maximum":100}},"required":["laneLimit"]}}}}}},"/api/v1/agents/{id}/repo-grants":{"get":{"responses":{"200":{"description":"OK"}},"operationId":"listAgentRepoGrants","tags":["Agents"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"List an agent's repository grants"},"post":{"responses":{"201":{"description":"Created"}},"operationId":"grantAgentRepo","tags":["Agents"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Grant an agent access to another repository","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"repo":{"type":"string","minLength":1,"maxLength":300}},"required":["repo"]}}}}}},"/api/v1/agents/{id}/repo-grants/{grantId}/revoke":{"post":{"responses":{"200":{"description":"OK"}},"operationId":"revokeAgentRepo","tags":["Agents"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true},{"in":"path","name":"grantId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Revoke an agent repository grant"}},"/api/v1/agents/{id}/heartbeat":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Agent"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"heartbeatAgent","tags":["Agents"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Bump last_seen_at"}},"/api/v1/agents/{id}/disconnect":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Agent"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"disconnectAgent","tags":["Agents"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark an agent as disconnected"}},"/api/v1/agents/{id}/wakeup-result":{"post":{"responses":{"201":{"description":"Wakeup result recorded","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentWakeupResult"}},"required":["data"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"recordAgentWakeupResult","tags":["Agents"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Record a scheduler-triggered wakeup outcome","description":"the agent calls this at the end of every wakeup. Also bumps last_seen_at (equivalent to heartbeat semantically). The status enum drives the scheduler's next-tick cadence.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["in_progress","compiling","testing","awaiting_review","blocked","complete","released","failed-validation"]},"commitSha":{"type":["string","null"]},"notes":{"type":["string","null"]},"nextWakeupHint":{"type":["string","null"],"enum":["normal","fast","slow","awaiting-external",null]}},"required":["status"]}}}}}},"/api/v1/agents/{id}/ceiling":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"},"personId":{"type":["string","null"]},"permissionKeys":{"type":"array","items":{"type":"string"}},"explicitExclusions":{"type":"array","items":{"type":"string"}},"snapshotAt":{"type":"string"}},"required":["agentId","personId","permissionKeys","explicitExclusions","snapshotAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getAgentPermissionCeiling","tags":["Agents"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get an agent's effective permission ceiling","description":"Intersection of the linked person's observed permissions and the app grant. Release promotion is always explicitly excluded."}},"/api/v1/agents/{id}/wakeup-results":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentWakeupResult"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listAgentWakeupResults","tags":["Agents"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"List recent wakeup results for an agent","description":"Ordered by at desc. Default limit 50."}},"/api/v1/agents/{id}/wakeup-result/latest":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentWakeupResult"}},"required":["data"]}}}},"404":{"description":"Agent has no wakeup results yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getLatestAgentWakeupResult","tags":["Agents"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get the most recent wakeup result for an agent","description":"Convenience for the scheduler: 'what was this agent's last status?' in one read."}},"/api/v1/agents/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Agent"}],"properties":{"personDisplayName":{"type":"object","properties":{"value":{"type":["string","null"]},"masked":{"type":"boolean"},"hint":{"type":["string","null"]}},"required":["value","masked","hint"]}},"required":["personDisplayName"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getAgent","tags":["Agents"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get an agent by id"}},"/api/v1/people":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"subjectId":{"type":"string"},"membershipId":{"type":["string","null"]},"roleKeys":{"type":"array","items":{"type":"string"}},"roleLabels":{"type":"array","items":{"type":"string"}},"permissionKeys":{"type":"array","items":{"type":"string"}},"membershipStatus":{"type":["string","null"]},"namesSnapshotAt":{"type":["string","null"]},"firstSeenAt":{"type":"string"},"lastSeenAt":{"type":"string"},"displayName":{"type":"object","properties":{"value":{"type":["string","null"]},"masked":{"type":"boolean"},"hint":{"type":["string","null"]}},"required":["value","masked","hint"]},"namesSource":{"type":"string","enum":["cache","unavailable"]},"namesAgeMs":{"type":["integer","null"],"minimum":0},"snapshotAt":{"type":["string","null"]},"agentsActive":{"type":"integer","minimum":0},"liveClaims":{"type":"integer","minimum":0},"isSelf":{"type":"boolean"}},"required":["subjectId","membershipId","roleKeys","roleLabels","permissionKeys","membershipStatus","namesSnapshotAt","firstSeenAt","lastSeenAt","displayName","namesSource","namesAgeMs","snapshotAt","agentsActive","liveClaims","isSelf"]}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listPeople","tags":["People"],"parameters":[{"in":"query","name":"role","schema":{"type":"string","minLength":1}},{"in":"query","name":"active","schema":{"type":"string","enum":["true","false"]}}],"summary":"List observed Dev people","description":"Viewer-aware local projection of staff observed through signed edge requests. Other people's names are masked server-side."}},"/api/v1/people/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"subjectId":{"type":"string"},"membershipId":{"type":["string","null"]},"roleKeys":{"type":"array","items":{"type":"string"}},"roleLabels":{"type":"array","items":{"type":"string"}},"permissionKeys":{"type":"array","items":{"type":"string"}},"membershipStatus":{"type":["string","null"]},"namesSnapshotAt":{"type":["string","null"]},"firstSeenAt":{"type":"string"},"lastSeenAt":{"type":"string"},"displayName":{"type":"object","properties":{"value":{"type":["string","null"]},"masked":{"type":"boolean"},"hint":{"type":["string","null"]}},"required":["value","masked","hint"]},"namesSource":{"type":"string","enum":["cache","unavailable"]},"namesAgeMs":{"type":["integer","null"],"minimum":0},"snapshotAt":{"type":["string","null"]},"isSelf":{"type":"boolean"},"agents":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}},"activeClaims":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["issue","feature_doc","request","slice"]},"id":{"type":"string"},"label":{"type":"string"},"agentId":{"type":["string","null"],"format":"uuid"},"expiresAt":{"type":["string","null"]}},"required":["kind","id","label","agentId","expiresAt"]}},"recentActivity":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"targetKind":{"type":"string"},"targetId":{"type":["string","null"]},"at":{"type":"string"}},"required":["action","targetKind","targetId","at"]}},"permissions":{"type":"array","items":{"type":"string"}}},"required":["subjectId","membershipId","roleKeys","roleLabels","permissionKeys","membershipStatus","namesSnapshotAt","firstSeenAt","lastSeenAt","displayName","namesSource","namesAgeMs","snapshotAt","isSelf","agents","activeClaims","recentActivity","permissions"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getPerson","tags":["People"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Get an observed Dev person"}},"/api/v1/people/{id}/reveal-name":{"post":{"responses":{"200":{"description":"Revealed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"value":{"type":["string","null"]},"masked":{"type":"boolean"},"hint":{"type":["string","null"]}},"required":["value","masked","hint"]}},"required":["data"]}}}}},"operationId":"revealPersonName","tags":["People"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Reveal one person's name","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"]}}}}}},"/api/v1/people/refresh-names":{"post":{"responses":{"200":{"description":"Refresh attempted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"namesSource":{"type":"string","enum":["cache","unavailable"]},"snapshotAt":{"type":["string","null"]},"ageMs":{"type":["integer","null"],"minimum":0},"refreshed":{"type":"integer","minimum":0},"reason":{"type":"string","enum":["unconfigured","forbidden","unavailable"]}},"required":["namesSource","snapshotAt","ageMs","refreshed"]}},"required":["data"]}}}}},"operationId":"refreshPeopleNames","tags":["People"],"parameters":[],"summary":"Refresh people names from tenant role holders","description":"Staff-only refresh. The route policy requires devops.agents.write; unavailable peer configuration is reported honestly."}},"/api/v1/doctrine":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GlobalDoctrine"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listDoctrine","tags":["Doctrine"],"parameters":[{"in":"query","name":"kind","schema":{"type":"string","enum":["global","workflow","module"]}},{"in":"query","name":"path_prefix","schema":{"type":"string"}},{"in":"query","name":"include_superseded","schema":{"type":"string","enum":["true","false"]}},{"in":"query","name":"include_deprecated","schema":{"type":"string","enum":["true","false"]}}],"summary":"List doctrine","description":"Returns latest version per path by default, including optional scope, enforcement and decisionRefs metadata. Pass include_superseded=true to get every row."},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GlobalDoctrine"}},"required":["data"]}}}},"409":{"description":"Path already exists — use /revise instead","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createDoctrine","tags":["Doctrine"],"parameters":[],"summary":"Create v1 of a new doctrine doc","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","minLength":1},"title":{"type":"string","minLength":1},"kind":{"type":"string","enum":["global","workflow","module"]},"scope":{"type":["string","null"],"minLength":1},"enforcement":{"type":["string","null"],"minLength":1},"decisionRefs":{"type":"array","items":{"type":"string","minLength":1},"maxItems":100},"bodyMd":{"type":"string","minLength":1},"sourceSha":{"type":["string","null"]}},"required":["path","title","kind","bodyMd"]}}}}}},"/api/v1/doctrine/{id}/deprecate":{"post":{"responses":{"200":{"description":"Deprecated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GlobalDoctrine"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deprecateDoctrine","tags":["Doctrine"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Soft-retire a doctrine row (excluded from the default list)","description":"Marks a doctrine row deprecated (e.g. an orphan from a defunct numbering scheme). It drops out of the default list but stays fetchable by id and recoverable. Idempotent.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1}},"required":["reason"]}}}}}},"/api/v1/doctrine/by-path/{path}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GlobalDoctrine"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getDoctrineByPath","tags":["Doctrine"],"parameters":[{"in":"path","name":"path","schema":{"type":"string","minLength":1},"required":true}],"summary":"Get latest doctrine revision by path"}},"/api/v1/doctrine/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GlobalDoctrine"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getDoctrine","tags":["Doctrine"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a specific doctrine revision"}},"/api/v1/doctrine/{id}/revise":{"post":{"responses":{"201":{"description":"Revised","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GlobalDoctrine"}},"required":["data"]}}}},"404":{"description":"Source doctrine row not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"reviseDoctrine","tags":["Doctrine"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Create v(N+1) of an existing doctrine doc","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1},"scope":{"type":["string","null"],"minLength":1},"enforcement":{"type":["string","null"],"minLength":1},"decisionRefs":{"type":"array","items":{"type":"string","minLength":1},"maxItems":100},"bodyMd":{"type":"string","minLength":1},"sourceSha":{"type":["string","null"]}},"required":["bodyMd"]}}}}}},"/api/v1/decisions":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Decision"}],"properties":{"amends":{"type":"array","items":{"type":"string"}},"buildsOn":{"type":"array","items":{"type":"string"}},"codificationState":{"type":"string","enum":["codified","debt","unknown","superseded"]}},"required":["amends","buildsOn","codificationState"]}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listDecisions","tags":["Decisions"],"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":500}},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0}},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["pending","locked","superseded"]},{"type":"array","items":{"type":"string","enum":["pending","locked","superseded"]}}]}},{"in":"query","name":"module","schema":{"type":"string"}},{"in":"query","name":"tag","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"since","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"includeSuperseded","schema":{"type":"string","enum":["true","false"]}}],"summary":"List decisions","description":"Superseded (dead) decisions are EXCLUDED by default — the agent-facing read only serves in-force decisions. Auditors opt in with `includeSuperseded=true`, or filter explicitly with `status=superseded`. Each row includes reverse `amends` ids and supersession-derived `buildsOn` ids."},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Decision"}},"required":["data"]}}}},"409":{"description":"Decision id already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createDecision","tags":["Decisions"],"parameters":[],"summary":"Create a decision","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^([a-z][a-z0-9_-]*-)?D\\d+$"},"title":{"type":"string","minLength":1},"module":{"type":"string","minLength":1},"topicTags":{"type":"array","items":{"type":"string"},"default":[]},"status":{"type":"string","enum":["pending","locked","superseded"],"default":"pending"},"bodyMd":{"type":"string","minLength":1},"supersedesId":{"type":["string","null"]},"lockedAt":{"type":["string","null"],"format":"date-time"},"autoLock":{"type":"boolean"}},"required":["id","title","module","bodyMd"]}}}}}},"/api/v1/decisions/codification-debt":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","minimum":0},"unknownCount":{"type":"integer","minimum":0},"evidenceSince":{"type":"string","format":"date-time"},"computedAt":{"type":"string","format":"date-time"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"lockedAt":{"type":"string","format":"date-time"},"ageSeconds":{"type":"integer","minimum":0}},"required":["id","title","lockedAt","ageSeconds"]}},"nextCursor":{"type":["string","null"]}},"required":["count","unknownCount","evidenceSince","computedAt","items","nextCursor"]}}}}},"operationId":"getDecisionCodificationDebt","tags":["Decisions"],"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"in":"query","name":"cursor","schema":{"type":"string","maxLength":500}}],"summary":"Get decision codification debt","description":"Counts uncited, non-superseded locked decisions since decisionRefs evidence began. Older uncited locks are reported separately as unknown. Items are oldest-first and keyset-paginated."}},"/api/v1/decisions/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Decision"}],"properties":{"bodyMd":{"type":"string"},"amendments":{"type":"array","items":{"$ref":"#/components/schemas/DecisionAmendment"}},"amends":{"type":"array","items":{"type":"string"}},"buildsOn":{"type":"array","items":{"type":"string"}},"codification":{"type":"object","properties":{"state":{"type":"string","enum":["codified","debt","unknown","superseded"]},"citedBy":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["feature_doc","doctrine"]},"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"version":{"type":"integer","exclusiveMinimum":0}},"required":["kind","id","key","version"]}}},"required":["state","citedBy"]}},"required":["bodyMd","amendments","amends","buildsOn","codification"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getDecision","tags":["Decisions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^([a-z][a-z0-9_-]*-)?D\\d+$"},"required":true},{"in":"query","name":"includeSuperseded","schema":{"type":"string","enum":["true","false"]}}],"summary":"Get a decision by id","description":"A dead (superseded / future tombstoned) decision returns a one-line tombstone body by default — its full dead text is never fed to an agent unless the auditor passes `includeSuperseded=true`. The original body is preserved in object storage; the collapse is applied at read time only. `amendments` lists the append-only amendment notes (POST /decisions/:id/amendments), oldest first; the stored body is never rewritten to carry them."},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Decision"}},"required":["data"]}}}},"403":{"description":"Non-operator tried to lock via PATCH","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"DECISION_LOCKED (ruling field on a locked/superseded decision) or DECISION_SUPERSEDE_VIA_ROUTE (status=superseded via PATCH)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateDecision","tags":["Decisions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^([a-z][a-z0-9_-]*-)?D\\d+$"},"required":true}],"summary":"Update a decision","description":"A `pending` decision may be edited freely (title, module, topicTags, bodyMd). A `locked` or `superseded` decision is IMMUTABLE: `title`, `bodyMd` and `status` are refused with 409 `DECISION_LOCKED`; only the catalog metadata `module` and `topicTags` may change. Record a later ruling against a locked decision with POST /decisions/:id/amendments. `status` cannot be set to `superseded` here (use /supersede), and setting `locked` is operator-only, exactly as POST /decisions/:id/lock.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1},"module":{"type":"string","minLength":1},"topicTags":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["pending","locked","superseded"]},"bodyMd":{"type":"string","minLength":1}}}}}}}},"/api/v1/decisions/{id}/amendments":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DecisionAmendment"}},"required":["data"]}}}},"404":{"description":"Target decision not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Target decision is not locked (DECISION_NOT_LOCKED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Amending decision missing / not locked / same as target (AMENDING_DECISION_NOT_FOUND, AMENDING_DECISION_NOT_LOCKED, DECISION_SELF_AMENDMENT)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createDecisionAmendment","tags":["Decisions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^([a-z][a-z0-9_-]*-)?D\\d+$"},"required":true}],"summary":"Append an amendment note to a locked decision","description":"The sanctioned way to record that a later LOCKED decision amends a locked one (PP-93, D1366). Appends a row to `decision_amendments`; the target's title, body and status are never changed. GET /decisions/:id returns the notes as `amendments`. The target must be `locked`; the amending decision must exist, be `locked`, and differ from the target.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amendedByDecisionId":{"type":"string","pattern":"^([a-z][a-z0-9_-]*-)?D\\d+$"},"note":{"type":"string","minLength":1,"maxLength":4000}},"required":["amendedByDecisionId","note"]}}}}}},"/api/v1/decisions/{id}/lock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Decision"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Cannot lock a superseded decision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"lockDecision","tags":["Decisions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^([a-z][a-z0-9_-]*-)?D\\d+$"},"required":true}],"summary":"Transition a decision to locked","description":"**Step 2 of the two-step workflow**: after creating a decision via POST /decisions (which creates it as `pending`), call this endpoint to lock it. Once locked, the decision is immutable and can be referenced from drift entries, feature_docs, and requests. To skip the two-step flow entirely, use `autoLock: true` on POST /decisions.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"lockedAt":{"type":"string","format":"date-time"}}}}}}}},"/api/v1/decisions/{id}/supersede":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Decision"}},"required":["data"]}}}},"404":{"description":"Source not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"New decision id already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"supersedeDecision","tags":["Decisions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^([a-z][a-z0-9_-]*-)?D\\d+$"},"required":true}],"summary":"Create a new decision that supersedes this one","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"newId":{"type":"string","pattern":"^([a-z][a-z0-9_-]*-)?D\\d+$"},"newTitle":{"type":"string","minLength":1},"newBodyMd":{"type":"string","minLength":1},"newTopicTags":{"type":"array","items":{"type":"string"}}},"required":["newId","newTitle","newBodyMd"]}}}}}},"/api/v1/feature-docs":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FeatureDoc"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listFeatureDocs","tags":["FeatureDocs"],"parameters":[{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["planned","approved","implementing","partially_implemented","implemented","superseded"]},{"type":"array","items":{"type":"string","enum":["planned","approved","implementing","partially_implemented","implemented","superseded"]}}]}},{"in":"query","name":"docKey","schema":{"type":"string"}},{"in":"query","name":"include_superseded","schema":{"type":"string","enum":["true","false"]}},{"in":"query","name":"claimed_by","schema":{"type":"string","format":"uuid"}}],"summary":"List feature docs (latest per (serviceId, docKey) by default)","description":"Includes optional area and decisionRefs metadata for each feature document."},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FeatureDoc"}},"required":["data"]}}}},"409":{"description":"(serviceId, docKey) already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Required H1 sections missing from body_md","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createFeatureDoc","tags":["FeatureDocs"],"parameters":[],"summary":"Create v1 of a feature doc","description":"Accepts optional area and decisionRefs metadata alongside the canonical body.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"serviceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"docKey":{"type":"string","pattern":"^[a-z][a-z0-9-]*$"},"title":{"type":"string","minLength":1},"area":{"type":["string","null"],"minLength":1},"decisionRefs":{"type":"array","items":{"type":"string","minLength":1},"maxItems":100},"bodyMd":{"type":"string","minLength":1}},"required":["serviceId","docKey","title","bodyMd"]}}}}}},"/api/v1/feature-docs/by-key/{serviceId}/{docKey}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FeatureDoc"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getFeatureDocByKey","tags":["FeatureDocs"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true},{"in":"path","name":"docKey","schema":{"type":"string","pattern":"^[a-z][a-z0-9-]*$"},"required":true}],"summary":"Get latest feature doc revision for (serviceId, docKey)"}},"/api/v1/feature-docs/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FeatureDoc"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getFeatureDoc","tags":["FeatureDocs"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a specific feature doc revision by id"}},"/api/v1/feature-docs/{id}/revise":{"post":{"responses":{"201":{"description":"Revised","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FeatureDoc"}},"required":["data"]}}}},"404":{"description":"Source revision not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"A later revision already exists; revise the new latest instead","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Required H1 sections missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"reviseFeatureDoc","tags":["FeatureDocs"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Create v(N+1) of a feature doc","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1},"area":{"type":["string","null"],"minLength":1},"decisionRefs":{"type":"array","items":{"type":"string","minLength":1},"maxItems":100},"bodyMd":{"type":"string","minLength":1}},"required":["bodyMd"]}}}}}},"/api/v1/feature-docs/{id}/claim":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FeatureDoc"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Lease held by another agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Cannot claim a feature doc that is not approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"claimFeatureDoc","tags":["FeatureDocs"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Lease a feature doc for implementation","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ttlMinutes":{"type":"integer","exclusiveMinimum":0,"maximum":1440}}}}}}}},"/api/v1/feature-docs/{id}/renew-claim":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FeatureDoc"}},"required":["data"]}}}},"403":{"description":"Lease not held by this agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"renewFeatureDocClaim","tags":["FeatureDocs"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Renew an existing claim's TTL","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ttlMinutes":{"type":"integer","exclusiveMinimum":0,"maximum":1440}}}}}}}},"/api/v1/feature-docs/{id}/release":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FeatureDoc"}},"required":["data"]}}}},"403":{"description":"Lease not held by this agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"releaseFeatureDocClaim","tags":["FeatureDocs"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Release a claim without completing"}},"/api/v1/feature-docs/{id}/complete":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FeatureDoc"}},"required":["data"]}}}},"403":{"description":"Lease not held","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"completeFeatureDoc","tags":["FeatureDocs"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a feature doc as implemented with the commit SHA","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"commitSha":{"type":"string","pattern":"^[0-9a-f]{7,40}$"}},"required":["commitSha"]}}}}}},"/api/v1/feature-docs/{id}/approve":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FeatureDoc"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Not in planned state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"approveFeatureDoc","tags":["FeatureDocs"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Transition planned → approved","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"approvedBy":{"type":"string"}}}}}}}},"/api/v1/feature-docs/{id}/status":{"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FeatureDoc"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"patchFeatureDocStatus","tags":["FeatureDocs"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update status (and optionally completionPct) of a feature doc","description":"Allows impl sessions to reconcile Dev status against real code state. Use status=partially_implemented + completionPct to show incremental progress.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["planned","approved","implementing","partially_implemented","implemented","superseded"]},"completionPct":{"type":["integer","null"],"minimum":0,"maximum":100},"commitSha":{"type":"string","pattern":"^[0-9a-f]{7,40}$"}},"required":["status"]}}}}}},"/api/v1/feature-docs/status-batch":{"post":{"responses":{"200":{"description":"OK — returns updated rows (missing ids silently skipped)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FeatureDoc"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"batchPatchFeatureDocStatus","tags":["FeatureDocs"],"parameters":[],"summary":"Batch-update status for up to 200 feature docs in one transaction","description":"Designed for the impl-session reconciliation pass: load current code state, diff against Dev statuses, patch all mismatches in one call.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"patches":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["planned","approved","implementing","partially_implemented","implemented","superseded"]},"completionPct":{"type":["integer","null"],"minimum":0,"maximum":100},"commitSha":{"type":"string","pattern":"^[0-9a-f]{7,40}$"}},"required":["id","status"]},"minItems":1,"maxItems":200}},"required":["patches"]}}}}}},"/api/v1/sagas":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Saga"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listSagas","tags":["Sagas"],"parameters":[{"in":"query","name":"orchestratorServiceId","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["planned","implemented","deprecated"]},{"type":"array","items":{"type":"string","enum":["planned","implemented","deprecated"]}}]}},{"in":"query","name":"involvesServiceId","schema":{"type":"string"}}],"summary":"List sagas"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Saga"}],"properties":{"steps":{"type":"array","items":{"$ref":"#/components/schemas/SagaStep"}}},"required":["steps"]}},"required":["data"]}}}},"409":{"description":"Saga name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createSaga","tags":["Sagas"],"parameters":[],"summary":"Create a saga (optionally with steps)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"orchestratorServiceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"descriptionMd":{"type":"string","minLength":1},"status":{"type":"string","enum":["planned","implemented","deprecated"]},"steps":{"type":"array","items":{"type":"object","properties":{"callsServiceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"callsRpc":{"type":"string","minLength":1},"compensationRpc":{"type":["string","null"]},"sync":{"type":"boolean"},"description":{"type":["string","null"]}},"required":["callsServiceId","callsRpc"]}}},"required":["name","orchestratorServiceId","descriptionMd"]}}}}}},"/api/v1/sagas/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Saga"}],"properties":{"steps":{"type":"array","items":{"$ref":"#/components/schemas/SagaStep"}}},"required":["steps"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getSaga","tags":["Sagas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a saga with embedded steps"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Saga"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateSaga","tags":["Sagas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update saga metadata","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"descriptionMd":{"type":"string","minLength":1},"status":{"type":"string","enum":["planned","implemented","deprecated"]}}}}}}},"delete":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Saga"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deprecateSaga","tags":["Sagas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Soft-delete (status=deprecated)"}},"/api/v1/sagas/{id}/steps":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SagaStep"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listSagaSteps","tags":["Sagas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"List steps for a saga"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SagaStep"}},"required":["data"]}}}},"404":{"description":"Saga not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"appendSagaStep","tags":["Sagas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Append a step to a saga","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"callsServiceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"callsRpc":{"type":"string","minLength":1},"compensationRpc":{"type":["string","null"]},"sync":{"type":"boolean"},"description":{"type":["string","null"]}},"required":["callsServiceId","callsRpc"]}}}}}},"/api/v1/sagas/{id}/implement":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Saga"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"implementSaga","tags":["Sagas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a saga as implemented","description":"Use after the orchestrator code is shipped + tested against the real backing stack per R1. Pairs with contract-lifecycle-progression skill."}},"/api/v1/sagas/{id}/steps/{stepId}":{"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SagaStep"}},"required":["data"]}}}},"404":{"description":"Step not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateSagaStep","tags":["Sagas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true},{"in":"path","name":"stepId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update a step","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"callsServiceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"callsRpc":{"type":"string","minLength":1},"compensationRpc":{"type":["string","null"]},"sync":{"type":"boolean"},"description":{"type":["string","null"]}}}}}}},"delete":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"removed":{"type":"string","format":"uuid"}},"required":["removed"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"removeSagaStep","tags":["Sagas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true},{"in":"path","name":"stepId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Remove a step (reorders remaining)"}},"/api/v1/sagas/{id}/reorder":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Saga"}],"properties":{"steps":{"type":"array","items":{"$ref":"#/components/schemas/SagaStep"}}},"required":["steps"]}},"required":["data"]}}}},"404":{"description":"Saga not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Order is not a valid permutation of existing steps","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"reorderSagaSteps","tags":["Sagas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Replace step ordering with a new permutation","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1}},"required":["order"]}}}}}},"/api/v1/sagas/{id}/lock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Saga"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"lockSaga","tags":["Sagas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Lock a saga's contract (freeze the minimum blueprint)","description":"Sets lockedAt/lockedByAgentId (+ optional lockedBySliceId). Orthogonal to status. Idempotent re-lock.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sliceId":{"type":"string","format":"uuid"}}}}}}}},"/api/v1/sagas/{id}/unlock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Saga"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unlockSaga","tags":["Sagas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Unlock a saga's contract (operator escape hatch)","description":"Clears lockedAt/lockedByAgentId/lockedBySliceId."}},"/api/v1/requests":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Request"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listRequests","tags":["Requests"],"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":500}},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0}},{"in":"query","name":"fromService","schema":{"type":"string"}},{"in":"query","name":"toService","schema":{"type":"string"}},{"in":"query","name":"serviceId","schema":{"type":"string"}},{"in":"query","name":"direction","schema":{"type":"string","enum":["inbound","outbound"]}},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["open","acknowledged","resolved","rejected"]},{"type":"array","items":{"type":"string","enum":["open","acknowledged","resolved","rejected"]}}]}},{"in":"query","name":"kind","schema":{"type":"string"}},{"in":"query","name":"includeExpired","schema":{"type":"string"}}],"summary":"List requests with filters"},"post":{"responses":{"201":{"description":"Created or existing returned","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Request"}},"required":["data"]}}}},"404":{"description":"Source or target service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"fileRequest","tags":["Requests"],"parameters":[],"summary":"File a cross-service request (idempotent on requestHash)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"requestHash":{"type":"string","pattern":"^[0-9a-f]{16}$"},"fromService":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"toService":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"kind":{"type":"string","minLength":1},"specMd":{"type":"string","minLength":1},"targetArtifactType":{"type":["string","null"]},"targetArtifactId":{"type":["string","null"]},"parentRequestId":{"type":["string","null"],"format":"uuid"},"requiredCapability":{"type":["string","null"]},"expiresAt":{"type":["string","null"],"format":"date-time"}},"required":["requestHash","fromService","toService","kind","specMd"]}}}}}},"/api/v1/requests/by-hash/{hash}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Request"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getRequestByHash","tags":["Requests"],"parameters":[{"in":"path","name":"hash","schema":{"type":"string","pattern":"^[0-9a-f]{16}$"},"required":true}],"summary":"Get a request by its request_hash"}},"/api/v1/requests/inbox/{serviceId}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Request"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"getRequestInbox","tags":["Requests"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["open","acknowledged"]},{"type":"array","items":{"type":"string","enum":["open","acknowledged"]}}]}}],"summary":"Pending requests targeting a service"}},"/api/v1/requests/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Request"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getRequest","tags":["Requests"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a request by id"}},"/api/v1/requests/{id}/acknowledge":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Request"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Invalid transition (not in 'open' status)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"acknowledgeRequest","tags":["Requests"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Acknowledge a request (open → acknowledged)"}},"/api/v1/requests/{id}/resolve":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Request"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Already resolved or rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"resolveRequest","tags":["Requests"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Resolve a request with a commit SHA","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"commitSha":{"type":"string","pattern":"^[0-9a-f]{7,40}$"},"resolutionMd":{"type":["string","null"]},"targetArtifactType":{"type":["string","null"]},"targetArtifactId":{"type":["string","null"]},"shippedVersion":{"type":["string","null"]}},"required":["commitSha"]}}}}}},"/api/v1/requests/{id}/reject":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Request"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"rejectRequest","tags":["Requests"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Reject a request with a reason","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"resolutionMd":{"type":"string","minLength":1}},"required":["resolutionMd"]}}}}}},"/api/v1/requests/{id}/claim":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Request"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Already claimed by another agent with a live lease","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Request is not in open/acknowledged status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"claimRequest","tags":["Requests"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Claim a request lease (prevents duplicate agent work)","description":"Acquires an exclusive lease on the request for the calling agent. Another agent may not claim the same request until the lease expires or is released. Pass ttlMinutes matching your expected work window (default 60).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ttlMinutes":{"type":"integer","minimum":1,"maximum":480}}}}}}}},"/api/v1/requests/{id}/release":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Request"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Caller is not the current claimant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"releaseRequest","tags":["Requests"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Release a previously claimed request lease"}},"/api/v1/requests/{id}/resolve-and-fan-out":{"post":{"responses":{"200":{"description":"OK — resolved row + count of fan-out notices filed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Request"},"fanOutCount":{"type":"number"}},"required":["data","fanOutCount"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Already resolved or rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"resolveAndFanOut","tags":["Requests"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Resolve a request and fan out inbox notices to sibling requestors","description":"Resolves the request and automatically files contract-vendor-ready-notice inbox messages to every open sibling request (same kind targeting the same service). Use this instead of plain /resolve when the resolution should propagate to services that filed related requests. Notices auto-expire in 30 days.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"commitSha":{"type":"string","pattern":"^[0-9a-f]{7,40}$"},"resolutionMd":{"type":["string","null"]},"shippedVersion":{"type":["string","null"]},"noticeKind":{"type":["string","null"]}},"required":["commitSha"]}}}}}},"/api/v1/audit-log":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditLog"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listAuditLog","tags":["AuditLog"],"parameters":[{"in":"query","name":"actor","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"actor_kind","schema":{"type":"string","enum":["agent","operator","system"]}},{"in":"query","name":"action","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"targetKind","schema":{"type":"string"}},{"in":"query","name":"targetId","schema":{"type":"string"}},{"in":"query","name":"since","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"until","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"limit","schema":{"type":"string","pattern":"^\\d+$"}},{"in":"query","name":"offset","schema":{"type":"string","pattern":"^\\d+$"}}],"summary":"List audit log entries with filters"}},"/api/v1/audit-log/by-target/{kind}/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditLog"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listAuditLogByTarget","tags":["AuditLog"],"parameters":[{"in":"path","name":"kind","schema":{"type":"string","minLength":1},"required":true},{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Chronological audit trail for a specific artifact"}},"/api/v1/audit-log/by-actor/{actor}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditLog"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listAuditLogByActor","tags":["AuditLog"],"parameters":[{"in":"path","name":"actor","schema":{"type":"string","minLength":1},"required":true},{"in":"query","name":"since","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"limit","schema":{"type":"string","pattern":"^\\d+$"}}],"summary":"Activity of a single actor"}},"/api/v1/audit-log/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AuditLog"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getAuditLogEntry","tags":["AuditLog"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get an audit log entry by id"}},"/api/v1/cron/tick":{"post":{"responses":{"201":{"description":"Tick recorded","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CronTick"}},"required":["data"]}}}}},"operationId":"recordCronTick","tags":["Cron"],"parameters":[],"summary":"Record a scheduler tick (liveness signal)","description":"Schedulers POST after each successful tick. External monitor reads `latest tick per name` and alerts on stale.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CronTickInsert"}}}}}},"/api/v1/cron/ticks/{name}/latest":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CronTick"}},"required":["data"]}}}},"404":{"description":"No ticks for this scheduler name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getLatestCronTickByName","tags":["Cron"],"parameters":[{"in":"path","name":"name","schema":{"type":"string","minLength":1,"maxLength":100},"required":true}],"summary":"Latest tick for a named scheduler"}},"/api/v1/cron/latest":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CronTick"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listLatestCronTicks","tags":["Cron"],"parameters":[],"summary":"Latest tick for every registered scheduler","description":"One row per distinct `name`. Dashboard for 'are all schedulers alive?'"}},"/api/v1/reconciliation/{kind}/{id}/mark-dirty":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReconciledContract"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"markContractDirty","tags":["Reconciliation"],"parameters":[{"in":"path","name":"kind","schema":{"type":"string","enum":["grpc-interface","rest-interface","outbox-topic","table","saga","approval-kind"]},"required":true},{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Flag a contract artifact dirty (needs reconciliation vs its impl)","description":"Sets reconciliation_state='dirty' + dirty_reason. Orthogonal to status/lock (a locked, implemented contract can be dirty). D378.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1}},"required":["reason"]}}}}}},"/api/v1/reconciliation/{kind}/{id}/reconcile":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReconciledContract"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"reconcileContract","tags":["Reconciliation"],"parameters":[{"in":"path","name":"kind","schema":{"type":"string","enum":["grpc-interface","rest-interface","outbox-topic","table","saga","approval-kind"]},"required":true},{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Reconcile a contract artifact clean (verified to match its impl)","description":"Sets reconciliation_state='clean', stamps reconciled_at/by, clears dirty_reason. Called by the impl agent after verifying the contract against code (verified-clean = reconciled_at set). D378.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string"}}}}}}}},"/api/v1/design/sync/catalog":{"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"syncDesignCatalog","tags":["Design"],"parameters":[],"summary":"Synchronize the design-system catalog","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string","minLength":1},"catalog":{"type":"object","properties":{"schema":{"type":"string","const":"nodii.design-catalog/v1"},"generatedFrom":{"type":"string","minLength":1},"figma":{"type":"object","properties":{"fileKey":{"type":"string"},"version":{"type":"string"},"lastModified":{"type":"string","format":"date-time"}},"required":["fileKey","version","lastModified"]},"groups":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["foundation","component","block","pattern"]},"key":{"type":"string"},"title":{"type":"string"},"ordinal":{"type":"integer"}},"required":["kind","key","title","ordinal"]}},"entries":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["foundation","component","block","pattern"]},"group":{"type":"string"},"parentKey":{"type":["string","null"]},"domain":{"type":["string","null"]},"switcherContext":{"type":["string","null"]},"module":{"type":["string","null"]},"status":{"type":"string","enum":["stable","beta","deprecated"]},"codePath":{"type":["string","null"]},"docsPath":{"type":["string","null"]},"figma":{"type":["object","null"],"properties":{"fileKey":{"type":"string"},"nodeId":{"type":"string"},"componentKey":{"type":"string"}},"required":["fileKey","nodeId","componentKey"]},"codeConnect":{"type":"boolean"},"variants":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"figmaNodeId":{"type":"string"}},"required":["name","figmaNodeId"]}},"slots":{"type":"array","items":{"type":"object","additionalProperties":{}}},"guidelines":{"type":"object","properties":{"path":{"type":["string","null"]},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"statement":{"type":"string"},"enforcement":{"type":"string","enum":["type","lint","validator","test","review","none"]},"enforcedBy":{"type":["string","null"]}},"required":["id","statement","enforcement","enforcedBy"]}}},"required":["path","rules"]},"consumers":{"type":["object","null"],"properties":{"switcherContexts":{"type":"array","items":{"type":"string"}},"modules":{"type":"array","items":{"type":"string"}},"measuredAt":{"type":"string","format":"date-time"},"source":{"type":"string"}},"required":["measuredAt","source"]}},"required":["key","title","kind","group","parentKey","domain","status","codePath","docsPath","figma","codeConnect","variants","slots","guidelines","consumers"]}}},"required":["schema","generatedFrom","figma","groups","entries"]}},"required":["ref","catalog"]}}}}}},"/api/v1/design/entries":{"get":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"listDesignEntries","tags":["Design"],"parameters":[{"in":"query","name":"kind","schema":{"type":"string","enum":["foundation","component","block","pattern"]}},{"in":"query","name":"group","schema":{"type":"string"}},{"in":"query","name":"q","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string"}},{"in":"query","name":"hasDeviation","schema":{"type":"string","enum":["true","false"]}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"in":"query","name":"cursor","schema":{"type":"string"}}],"summary":"List tree-ready design entries"}},"/api/v1/design/entries/{key}":{"get":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"getDesignEntry","tags":["Design"],"parameters":[{"in":"path","name":"key","schema":{"type":"string","minLength":1},"required":true}],"summary":"Get a design entry"}},"/api/v1/design/guides/{key}":{"get":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"getDesignGuide","tags":["Design"],"parameters":[{"in":"path","name":"key","schema":{"type":"string","minLength":1},"required":true}],"summary":"Get the rules, pattern and blocks for a page type"}},"/api/v1/design/files":{"get":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"listDesignFiles","tags":["Design"],"parameters":[],"summary":"List design files"}},"/api/v1/design/change-sets":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"fileKey":{"type":"string"},"state":{"type":"string","enum":["editing","in_review","applying","awaiting_publish","published","abandoned"]},"baseVersion":{"type":["string","null"]},"submittedVersions":{"type":"array","items":{"type":"string"}},"approvedVersion":{"type":["string","null"]},"publishedVersion":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"closedAt":{"type":["string","null"]},"file":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["design-system","surfaces","prototype"]}},"required":["key","name","kind"]},"holder":{"type":"object","properties":{"person":{"type":["object","null"],"properties":{"id":{"type":"string"},"displayName":{"type":"object","properties":{"value":{"type":["string","null"]},"masked":{"type":"boolean"},"hint":{"type":["string","null"]}},"required":["value","masked","hint"]}},"required":["id","displayName"]},"agent":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"displayName":{"type":["string","null"]}},"required":["id","displayName"]}},"required":["person","agent"]},"itemCounts":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"decided":{"type":"integer","minimum":0},"approved":{"type":"integer","minimum":0},"rejected":{"type":"integer","minimum":0},"pending":{"type":"integer","minimum":0}},"required":["total","decided","approved","rejected","pending"]}},"required":["id","title","fileKey","state","baseVersion","submittedVersions","approvedVersion","publishedVersion","createdAt","updatedAt","closedAt","file","holder","itemCounts"]}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listDesignChangeSets","tags":["Design"],"parameters":[{"in":"query","name":"fileKey","schema":{"type":"string","minLength":1}},{"in":"query","name":"state","schema":{"anyOf":[{"type":"string","enum":["editing","in_review","applying","awaiting_publish","published","abandoned"]},{"type":"array","items":{"type":"string","enum":["editing","in_review","applying","awaiting_publish","published","abandoned"]}}]}},{"in":"query","name":"q","schema":{"type":"string","minLength":1}},{"in":"query","name":"sort","schema":{"type":"string","enum":["newest","oldest"],"default":"newest"}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0}}],"summary":"List design change sets"}},"/api/v1/design/change-sets/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"fileKey":{"type":"string"},"state":{"type":"string","enum":["editing","in_review","applying","awaiting_publish","published","abandoned"]},"baseVersion":{"type":["string","null"]},"submittedVersions":{"type":"array","items":{"type":"string"}},"approvedVersion":{"type":["string","null"]},"publishedVersion":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"closedAt":{"type":["string","null"]},"file":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["design-system","surfaces","prototype"]}},"required":["key","name","kind"]},"holder":{"type":"object","properties":{"person":{"type":["object","null"],"properties":{"id":{"type":"string"},"displayName":{"type":"object","properties":{"value":{"type":["string","null"]},"masked":{"type":"boolean"},"hint":{"type":["string","null"]}},"required":["value","masked","hint"]}},"required":["id","displayName"]},"agent":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"displayName":{"type":["string","null"]}},"required":["id","displayName"]}},"required":["person","agent"]},"itemCounts":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"decided":{"type":"integer","minimum":0},"approved":{"type":"integer","minimum":0},"rejected":{"type":"integer","minimum":0},"pending":{"type":"integer","minimum":0}},"required":["total","decided","approved","rejected","pending"]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"changeSetId":{"type":"string"},"entryKey":{"type":["string","null"]},"figmaNodeId":{"type":"string"},"change":{"type":"string","enum":["changed","new","removed"]},"decision":{"type":"string","enum":["pending","approved","rejected"]},"comment":{"type":["string","null"]},"decidedBy":{"type":["string","null"]},"decidedAt":{"type":["string","null"]},"round":{"type":"integer","exclusiveMinimum":0},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"itemId":{"type":"string","format":"uuid"},"figmaNodeId":{"type":"string"},"beforeImageId":{"type":["string","null"],"format":"uuid"},"afterImageId":{"type":["string","null"],"format":"uuid"}},"required":["id","itemId","figmaNodeId","beforeImageId","afterImageId"]}}},"required":["id","changeSetId","entryKey","figmaNodeId","change","decision","comment","decidedBy","decidedAt","round","variants"]}},"writeLog":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"changeSetId":{"type":"string"},"agentId":{"type":"string","format":"uuid"},"tool":{"type":"string"},"nodeIds":{"type":"array","items":{"type":"string"}},"at":{"type":"string"}},"required":["id","changeSetId","agentId","tool","nodeIds","at"]}}},"required":["id","title","fileKey","state","baseVersion","submittedVersions","approvedVersion","publishedVersion","createdAt","updatedAt","closedAt","file","holder","itemCounts","items","writeLog"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getDesignChangeSet","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Get a design change set with review items and write log"}},"/api/v1/design/files/{key}":{"get":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"getDesignFile","tags":["Design"],"parameters":[{"in":"path","name":"key","schema":{"type":"string","minLength":1},"required":true}],"summary":"Get a design file"}},"/api/v1/design/files/{key}/lock":{"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"claimDesignFileLock","tags":["Design"],"parameters":[{"in":"path","name":"key","schema":{"type":"string","minLength":1},"required":true}],"summary":"Claim a design file lock","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"changeSetTitle":{"type":"string","minLength":1}},"required":["changeSetTitle"]}}}}}},"/api/v1/design/files/{key}/lock/check":{"get":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"checkDesignFileLock","tags":["Design"],"parameters":[{"in":"path","name":"key","schema":{"type":"string","minLength":1},"required":true},{"in":"query","name":"agentId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Check whether an agent may write"}},"/api/v1/design/files/{key}/lock/release":{"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"forceReleaseDesignFileLock","tags":["Design"],"parameters":[{"in":"path","name":"key","schema":{"type":"string","minLength":1},"required":true}],"summary":"Force-release a design file lock"}},"/api/v1/design/change-sets/{id}/writes":{"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"logDesignWrite","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Log a Figma write","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string","minLength":1},"nodeIds":{"type":"array","items":{"type":"string"},"minItems":1}},"required":["tool","nodeIds"]}}}}}},"/api/v1/design/change-sets/{id}/submit":{"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"submitDesignChangeSet","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Submit a design change set","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"figmaVersion":{"type":"string","minLength":1},"items":{"type":"array","items":{"type":"object","properties":{"entryKey":{"type":"string"},"figmaNodeId":{"type":"string"},"change":{"type":"string","enum":["changed","new","removed"]},"variants":{"type":"array","items":{"type":"object","properties":{"nodeId":{"type":"string"},"beforePngBase64":{"type":"string"},"afterPngBase64":{"type":"string"}},"required":["nodeId"]}}},"required":["figmaNodeId","change","variants"]},"minItems":1}},"required":["figmaVersion","items"]}}}}}},"/api/v1/design/change-items/{id}/decide":{"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"decideDesignChangeItem","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Approve or reject a design item","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["approved","rejected"]},"comment":{"type":"string"}},"required":["decision"]}}}}}},"/api/v1/design/change-sets/{id}/apply":{"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"applyDesignChangeSet","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Record application of approved changes","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"figmaVersion":{"type":"string"}},"required":["figmaVersion"]}}}}}},"/api/v1/design/change-sets/{id}/published":{"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"publishDesignChangeSet","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Close a published change set","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"figmaVersion":{"type":"string"}},"required":["figmaVersion"]}}}}}},"/api/v1/design/change-sets/{id}/abandon":{"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"abandonDesignChangeSet","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Abandon a design change set"}},"/api/v1/design/rules":{"get":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"listDesignRules","tags":["Design"],"parameters":[],"summary":"List design rules"}},"/api/v1/design/rules/{id}":{"get":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"getDesignRule","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Get a design rule"}},"/api/v1/design/rules/{id}/lock":{"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"lockDesignRule","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"lock a design rule","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"supersededBy":{"type":"string"}}}}}}}},"/api/v1/design/rules/{id}/retire":{"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"retireDesignRule","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"retire a design rule","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"supersededBy":{"type":"string"}}}}}}}},"/api/v1/design/conflicts":{"get":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"listDesignConflicts","tags":["Design"],"parameters":[],"summary":"List design conflicts"},"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"createDesignConflict","tags":["Design"],"parameters":[],"summary":"Create a design conflict","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"memberKeys":{"type":"array","items":{"type":"string"},"minItems":2},"description":{"type":"string"},"usage":{"type":"object","additionalProperties":{},"default":{}},"proposedResolution":{"type":"string"}},"required":["title","memberKeys","description"]}}}}}},"/api/v1/design/conflicts/{id}":{"patch":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"updateDesignConflict","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Update a design conflict","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"usage":{"type":"object","additionalProperties":{}},"proposedResolution":{"type":["string","null"]},"resolution":{"type":"string","enum":["open","merge","keep-distinct","move-to-surfaces","escalated"]}}}}}}}},"/api/v1/design/deviations":{"get":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"listDesignDeviations","tags":["Design"],"parameters":[],"summary":"List design deviations"}},"/api/v1/design/images/{id}/raw":{"get":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"getDesignImageRaw","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Stream an immutable design PNG"}},"/api/v1/design/summary":{"get":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"getDesignSummary","tags":["Design"],"parameters":[],"summary":"Get design governance summary"}},"/api/v1/ideas":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"summary":{"type":"string"},"detail":{"type":["string","null"]},"status":{"type":"string","enum":["captured","exploring","promoted","dropped"]},"promotedLink":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","summary","detail","status","promotedLink","createdByAgentId","createdAt","updatedAt"]}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listIdeas","tags":["Ideas"],"parameters":[{"in":"query","name":"q","schema":{"type":"string","minLength":1}},{"in":"query","name":"status","schema":{"type":"string","enum":["captured","exploring","promoted","dropped"]}}],"summary":"List and search ideas"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"summary":{"type":"string"},"detail":{"type":["string","null"]},"status":{"type":"string","enum":["captured","exploring","promoted","dropped"]},"promotedLink":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","summary","detail","status","promotedLink","createdByAgentId","createdAt","updatedAt"]}},"required":["data"]}}}}},"operationId":"createIdea","tags":["Ideas"],"parameters":[],"summary":"Quick-capture an idea","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"string","minLength":1,"maxLength":280},"detail":{"type":"string","minLength":1}},"required":["summary"],"additionalProperties":false}}}}}},"/api/v1/ideas/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"summary":{"type":"string"},"detail":{"type":["string","null"]},"status":{"type":"string","enum":["captured","exploring","promoted","dropped"]},"promotedLink":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","summary","detail","status","promotedLink","createdByAgentId","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getIdea","tags":["Ideas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get an idea"}},"/api/v1/ideas/{id}/status":{"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"summary":{"type":"string"},"detail":{"type":["string","null"]},"status":{"type":"string","enum":["captured","exploring","promoted","dropped"]},"promotedLink":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","summary","detail","status","promotedLink","createdByAgentId","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateIdeaStatus","tags":["Ideas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update an idea status","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["captured","exploring","promoted","dropped"]},"promotedLink":{"type":"string","format":"uri"}},"required":["status"],"additionalProperties":false}}}}}},"/api/v1/swaps":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fromPattern":{"type":"string"},"toPattern":{"type":"string"},"whyDecisionLink":{"type":"string"},"detectorKind":{"type":"string"},"detectorExpression":{"type":"string"},"guideLink":{"type":"string"},"examplePrLink":{"type":["string","null"]},"owner":{"type":"string"},"switcherContexts":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["open","closed"]},"closedAt":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"openSites":{"type":"integer"},"swappedSites":{"type":"integer"},"verifiedSites":{"type":"integer"},"totalSites":{"type":"integer"}},"required":["id","fromPattern","toPattern","whyDecisionLink","detectorKind","detectorExpression","guideLink","examplePrLink","owner","switcherContexts","status","closedAt","createdByAgentId","createdAt","updatedAt","openSites","swappedSites","verifiedSites","totalSites"]}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listSwaps","tags":["Swaps"],"parameters":[{"in":"query","name":"q","schema":{"type":"string","minLength":1}},{"in":"query","name":"status","schema":{"type":"string","enum":["open","closed"]}},{"in":"query","name":"switcherContext","schema":{"type":"string","minLength":1}}],"summary":"List swaps with progress counts"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fromPattern":{"type":"string"},"toPattern":{"type":"string"},"whyDecisionLink":{"type":"string"},"detectorKind":{"type":"string"},"detectorExpression":{"type":"string"},"guideLink":{"type":"string"},"examplePrLink":{"type":["string","null"]},"owner":{"type":"string"},"switcherContexts":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["open","closed"]},"closedAt":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","fromPattern","toPattern","whyDecisionLink","detectorKind","detectorExpression","guideLink","examplePrLink","owner","switcherContexts","status","closedAt","createdByAgentId","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createSwap","tags":["Swaps"],"parameters":[],"summary":"Declare an old to new swap","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fromPattern":{"type":"string","minLength":1},"toPattern":{"type":"string","minLength":1},"whyDecisionLink":{"type":"string","format":"uri"},"detectorKind":{"type":"string","enum":["grep","lint"]},"detectorExpression":{"type":"string","minLength":1},"guideLink":{"type":"string","format":"uri"},"examplePrLink":{"type":"string","format":"uri"},"owner":{"type":"string","minLength":1},"switcherContexts":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["fromPattern","toPattern","whyDecisionLink","detectorKind","detectorExpression","guideLink","owner","switcherContexts"],"additionalProperties":false}}}}}},"/api/v1/swaps/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fromPattern":{"type":"string"},"toPattern":{"type":"string"},"whyDecisionLink":{"type":"string"},"detectorKind":{"type":"string"},"detectorExpression":{"type":"string"},"guideLink":{"type":"string"},"examplePrLink":{"type":["string","null"]},"owner":{"type":"string"},"switcherContexts":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["open","closed"]},"closedAt":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"openSites":{"type":"integer"},"swappedSites":{"type":"integer"},"verifiedSites":{"type":"integer"},"totalSites":{"type":"integer"},"sites":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"swapId":{"type":"string","format":"uuid"},"repository":{"type":"string"},"filePath":{"type":["string","null"]},"line":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"route":{"type":["string","null"]},"switcherContext":{"type":["string","null"]},"status":{"type":"string","enum":["open","swapped","verified"]},"prLink":{"type":["string","null"]},"discoveredBy":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","swapId","repository","filePath","line","route","switcherContext","status","prLink","discoveredBy","createdAt","updatedAt"]}}},"required":["id","fromPattern","toPattern","whyDecisionLink","detectorKind","detectorExpression","guideLink","examplePrLink","owner","switcherContexts","status","closedAt","createdByAgentId","createdAt","updatedAt","openSites","swappedSites","verifiedSites","totalSites","sites"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getSwap","tags":["Swaps"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a swap, progress and sites"}},"/api/v1/swaps/{swapId}/sites":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"swapId":{"type":"string","format":"uuid"},"repository":{"type":"string"},"filePath":{"type":["string","null"]},"line":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"route":{"type":["string","null"]},"switcherContext":{"type":["string","null"]},"status":{"type":"string","enum":["open","swapped","verified"]},"prLink":{"type":["string","null"]},"discoveredBy":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","swapId","repository","filePath","line","route","switcherContext","status","prLink","discoveredBy","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createSwapSite","tags":["Swaps"],"parameters":[{"in":"path","name":"swapId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Record a site of an old pattern","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"repository":{"type":"string","minLength":1},"filePath":{"type":"string","minLength":1},"line":{"type":"integer","minimum":1},"route":{"type":"string","minLength":1},"switcherContext":{"type":"string","minLength":1},"discoveredBy":{"type":"string","enum":["detector","agent"],"default":"agent"}},"required":["repository"],"additionalProperties":false}}}}}},"/api/v1/swaps/sites/{id}/status":{"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"swapId":{"type":"string","format":"uuid"},"repository":{"type":"string"},"filePath":{"type":["string","null"]},"line":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"route":{"type":["string","null"]},"switcherContext":{"type":["string","null"]},"status":{"type":"string","enum":["open","swapped","verified"]},"prLink":{"type":["string","null"]},"discoveredBy":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","swapId","repository","filePath","line","route","switcherContext","status","prLink","discoveredBy","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateSwapSiteStatus","tags":["Swaps"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Move a swap site through open, swapped and verified","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["open","swapped","verified"]},"prLink":{"type":"string","format":"uri"}},"required":["status"],"additionalProperties":false}}}}}},"/api/v1/swaps/{id}/close":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fromPattern":{"type":"string"},"toPattern":{"type":"string"},"whyDecisionLink":{"type":"string"},"detectorKind":{"type":"string"},"detectorExpression":{"type":"string"},"guideLink":{"type":"string"},"examplePrLink":{"type":["string","null"]},"owner":{"type":"string"},"switcherContexts":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["open","closed"]},"closedAt":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","fromPattern","toPattern","whyDecisionLink","detectorKind","detectorExpression","guideLink","examplePrLink","owner","switcherContexts","status","closedAt","createdByAgentId","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"closeSwap","tags":["Swaps"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Close a swap when no open sites remain"}},"/api/v1/terminology":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"term":{"type":"string"},"definition":{"type":"string"},"not":{"type":"array","items":{"type":"string"}},"whereUsed":{"type":"array","items":{"type":"string"}},"bannedSynonyms":{"type":"array","items":{"type":"string"}},"source":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","term","definition","not","whereUsed","bannedSynonyms","source","createdAt","updatedAt"]}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listTerminology","tags":["Terminology"],"parameters":[{"in":"query","name":"q","schema":{"type":"string","minLength":1}},{"in":"query","name":"hasBannedSynonyms","schema":{"type":"string","enum":["true","false"]}}],"summary":"List and search global terminology"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"term":{"type":"string"},"definition":{"type":"string"},"not":{"type":"array","items":{"type":"string"}},"whereUsed":{"type":"array","items":{"type":"string"}},"bannedSynonyms":{"type":"array","items":{"type":"string"}},"source":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","term","definition","not","whereUsed","bannedSynonyms","source","createdAt","updatedAt"]}},"required":["data"]}}}},"409":{"description":"Term exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createTerminologyTerm","tags":["Terminology"],"parameters":[],"summary":"Create a terminology term","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"term":{"type":"string","minLength":1,"maxLength":120},"definition":{"type":"string","minLength":1},"not":{"type":"array","items":{"type":"string","minLength":1},"default":[]},"whereUsed":{"type":"array","items":{"type":"string","minLength":1},"default":[]},"bannedSynonyms":{"type":"array","items":{"type":"string","minLength":1},"default":[]},"source":{"type":["string","null"],"minLength":1}},"required":["term","definition"],"additionalProperties":false}}}}}},"/api/v1/terminology/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"term":{"type":"string"},"definition":{"type":"string"},"not":{"type":"array","items":{"type":"string"}},"whereUsed":{"type":"array","items":{"type":"string"}},"bannedSynonyms":{"type":"array","items":{"type":"string"}},"source":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","term","definition","not","whereUsed","bannedSynonyms","source","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getTerminologyTerm","tags":["Terminology"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a terminology term"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"term":{"type":"string"},"definition":{"type":"string"},"not":{"type":"array","items":{"type":"string"}},"whereUsed":{"type":"array","items":{"type":"string"}},"bannedSynonyms":{"type":"array","items":{"type":"string"}},"source":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","term","definition","not","whereUsed","bannedSynonyms","source","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateTerminologyTerm","tags":["Terminology"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update a terminology term","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"term":{"type":"string","minLength":1,"maxLength":120},"definition":{"type":"string","minLength":1},"not":{"type":"array","items":{"type":"string","minLength":1},"default":[]},"whereUsed":{"type":"array","items":{"type":"string","minLength":1},"default":[]},"bannedSynonyms":{"type":"array","items":{"type":"string","minLength":1},"default":[]},"source":{"type":["string","null"],"minLength":1}},"additionalProperties":false}}}}}},"/api/v1/services/{serviceId}/projects":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createProject","tags":["Projects"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","minLength":1},"required":true}],"summary":"Create a project (draft) — the bounded unit-of-implementation (D387)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"projectKey":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]*$","minLength":1},"title":{"type":"string","minLength":1},"summary":{"type":"string"},"planMd":{"type":"string"}},"required":["projectKey","title"]}}}}},"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceProjects","tags":["Projects"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","minLength":1},"required":true}],"summary":"List a service's projects"}},"/api/v1/projects/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getProject","tags":["Projects"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a project + its doctrine-coverage"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateProject","tags":["Projects"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update a project's title / summary / plan","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1},"summary":{"type":["string","null"]},"planMd":{"type":["string","null"]}}}}}}}},"/api/v1/projects/{id}/coverage":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProjectDoctrineCoverage"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"setProjectCoverage","tags":["Projects"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Set doctrine-coverage lines for a project (bulk upsert)","description":"One line per global doctrine (applicable: how / not-applicable: why). A project's scope can only be confirmed once every canonical global doctrine has a coverage line (D387).","requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"doctrineKey":{"type":"string","enum":["01-communication-doctrine","02-audit-doctrine","03-logging-doctrine","04-pii-doctrine","05-platform-tenant","06-library-integration","07-rbac-doctrine","08-rls-doctrine","09-replication-doctrine","10-approval-doctrine","11-dsar-doctrine","12-testing-doctrine","13-module-independence-doctrine","14-entity-authority-doctrine","15-telemetry-doctrine","16-obs-retention-and-backups-doctrine","17-infra-shape-doctrine","18-alerting-doctrine","19-self-monitoring-and-dr-doctrine","20-client-sdk-doctrine","21-oob-notification-delivery-doctrine","22-infra-obs-for-pane-doctrine"]},"applicability":{"type":"string","enum":["applicable","not-applicable"]},"note":{"type":"string","minLength":1}},"required":["doctrineKey","applicability","note"]},"minItems":1}}}}}},"/api/v1/projects/{id}/confirm-scope":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Scope incomplete / bad status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"confirmProjectScope","tags":["Projects"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Confirm scope (draft -> scope_confirmed) — GATED on full doctrine coverage","description":"Refuses with 422 PROJECT_SCOPE_INCOMPLETE + the missing doctrine list until every canonical global doctrine has a coverage line (D387)."}},"/api/v1/projects/{id}/transition":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"transitionProject","tags":["Projects"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Transition a project's status (implementing / verifying / complete / abandoned)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["implementing","verifying","complete","abandoned"]}},"required":["status"]}}}}}},"/api/v1/projects/{id}/findings":{"post":{"responses":{"200":{"description":"Routed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"routed":{"type":"number"},"notFound":{"type":"array","items":{"type":"string"}}},"required":["routed","notFound"]}},"required":["data"]}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"routeProjectFindings","tags":["Projects"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Route discovery findings (drift entries) into a project's scope","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"driftIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1}},"required":["driftIds"]}}}}}},"/api/v1/projects/{id}/findings/{driftId}":{"delete":{"responses":{"200":{"description":"Unrouted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"unrouted":{"type":"boolean","const":true}},"required":["unrouted"]}},"required":["data"]}}}},"404":{"description":"No such finding routed to this project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unrouteProjectFinding","tags":["Projects"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true},{"in":"path","name":"driftId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Un-route a finding from a project (clears its project_id)"}},"/api/v1/services/{serviceId}/slices":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Slice"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceSlices","tags":["Slices"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"List a service's implementation slices","description":"Returns every slice for the service, ordered by dagOrder then sliceKey."},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Slice"}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"(serviceId, sliceKey) already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createServiceSlice","tags":["Slices"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Create an implementation slice for a service","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sliceKey":{"type":"string","pattern":"^[a-z][a-z0-9-]*$"},"title":{"type":"string","minLength":1},"splitConcurrency":{"type":"integer","exclusiveMinimum":0},"dagOrder":{"type":"integer","minimum":0},"descriptionMd":{"type":"string","minLength":1}},"required":["sliceKey","title"]}}}}}},"/api/v1/slices/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Slice"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getSlice","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a slice by id"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Slice"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateSlice","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update a slice's mutable fields","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1},"splitConcurrency":{"type":"integer","exclusiveMinimum":0},"dagOrder":{"type":"integer","minimum":0},"status":{"type":"string","enum":["planned","locked","implementing","partially_implemented","implemented","deprecated"]},"completionPct":{"type":["integer","null"],"minimum":0,"maximum":100},"descriptionMd":{"type":"string","minLength":1}}}}}}}},"/api/v1/slices/{id}/lock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Slice"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Locked by another agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Owned minimums are not all locked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"lockSlice","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Lock a slice's minimum contract surface","description":"Sets lockedAt + lockedByAgentId. Gated on owned minimums: 422 SLICE_MINIMUMS_UNLOCKED (with the unlocked rows in details) when any owned slice_minimum is unlocked. Idempotent if already locked by the same agent; 409 LOCK_CONFLICT if locked by another agent."}},"/api/v1/slices/{id}/unlock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Slice"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unlockSlice","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Unlock a slice (operator escape hatch)","description":"Clears lockedAt + lockedByAgentId; rewinds locked → planned."}},"/api/v1/slices/{id}/implement":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Slice"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"implementSlice","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a slice implemented","description":"Sets status → implemented and completionPct → 100."}},"/api/v1/slices/{id}/claim":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Slice"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Lease held by another agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"claimSlice","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Acquire the slice work lease (CAS)","description":"Succeeds only when the lease is free, expired, or already held by the caller. Sets claimedByAgentId + claimExpiresAt = now + ttl (default 30 min). 409 SLICE_CLAIM_HELD on a lost race.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ttlMinutes":{"type":"integer","exclusiveMinimum":0,"maximum":1440}}}}}}}},"/api/v1/slices/{id}/release":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Slice"}},"required":["data"]}}}},"403":{"description":"Lease not held by this agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"releaseSlice","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Release the slice work lease","description":"Only the current holder (or an operator) may release. 403 if not the holder."}},"/api/v1/slices/{id}/feature-docs":{"post":{"responses":{"201":{"description":"Attached","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SliceFeatureDoc"}},"required":["data"]}}}},"404":{"description":"Slice or feature_doc not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"feature_doc belongs to a different service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"attachSliceFeatureDoc","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Attach a feature_doc to a slice (ownership)","description":"Records that the slice OWNS the feature_doc. Rejects 422 SLICE_FEATURE_DOC_SERVICE_MISMATCH when the feature_doc belongs to a different service. Idempotent on (sliceId, featureDocId).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"featureDocId":{"type":"string","format":"uuid"}},"required":["featureDocId"]}}}}},"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SliceFeatureDocEnriched"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listSliceFeatureDocs","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"List the feature_docs a slice owns"}},"/api/v1/slices/{id}/feature-docs/{featureDocId}":{"delete":{"responses":{"200":{"description":"Detached","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"detached":{"type":"boolean","const":true}},"required":["detached"]}},"required":["data"]}}}},"404":{"description":"No such ownership join","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"detachSliceFeatureDoc","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true},{"in":"path","name":"featureDocId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Detach a feature_doc from a slice"}},"/api/v1/slices/{id}/minimums":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SliceMinimum"}},"required":["data"]}}}},"404":{"description":"Slice not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"(sliceId, kind, name) already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createSliceMinimum","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Declare a minimum-shape seam on a slice","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["module_fn","module_type","internal_table_cols","constant","rest_surface","event_schema","cli_invocation"]},"name":{"type":"string","minLength":1},"signatureMd":{"type":"string","maxLength":2048},"shapeMd":{"type":"string","minLength":1}},"required":["kind","name"]}}}}},"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SliceMinimum"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listSliceMinimums","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"List a slice's minimums"}},"/api/v1/minimums/{id}/lock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SliceMinimum"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Locked by another agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"lockSliceMinimum","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Lock a minimum's shape (floor frozen)","description":"Idempotent if already locked by the same agent; 409 MINIMUM_LOCK_CONFLICT if locked by another agent."}},"/api/v1/minimums/{id}/unlock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SliceMinimum"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unlockSliceMinimum","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Unlock a minimum (operator escape hatch)"}},"/api/v1/minimums/{id}/implement":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SliceMinimum"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"implementSliceMinimum","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a minimum implemented"}},"/api/v1/slices/{id}/boundary-contracts":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SliceBoundaryContract"}},"required":["data"]}}}},"404":{"description":"Producer slice / referenced artifact / minimum not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Duplicate boundary contract","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Reference fields incomplete or invalid for refKind","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createSliceBoundaryContract","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Declare a cross-boundary contract from a producer slice","description":"refKind=artifact points at an existing Dev artifact row (validated to exist); refKind=minimum points at one of the slice's minimums. Deduped via NULLS NOT DISTINCT → 409 BOUNDARY_DUPLICATE on a repeat.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"consumerSliceId":{"type":"string","format":"uuid"},"consumerServiceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"refKind":{"type":"string","enum":["artifact","minimum"]},"artifactType":{"type":"string","enum":["grpc","rest","table","outbox","saga","sql"]},"artifactId":{"type":"string","format":"uuid"},"minimumId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["declared","locked","satisfied"]}},"required":["refKind"]}}}}},"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SliceBoundaryContract"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listSliceBoundaryContracts","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"List a producer slice's boundary contracts"}},"/api/v1/slices/{id}/deps":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SliceDep"}},"required":["data"]}}}},"404":{"description":"Slice or dependency target not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Edge already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Self-ref, cross-service, or cycle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"addSliceDep","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Add an intra-service dependency edge between slices","description":"Rejects self-references, cross-service deps, duplicates, and 422 SLICE_DEP_CYCLE when the edge would close a cycle (WITH RECURSIVE).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"dependsOnSliceId":{"type":"string","format":"uuid"}},"required":["dependsOnSliceId"]}}}}},"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SliceDep"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listSliceDeps","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"List a slice's dependency edges"}},"/api/v1/slices/{id}/recompute-status":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Slice"},"facts":{"type":"object","properties":{"sliceId":{"type":"string"},"featureDocsTotal":{"type":"integer"},"featureDocsImplemented":{"type":"integer"},"featureDocsPartiallyImplemented":{"type":"integer"},"featureDocsImplementing":{"type":"integer"},"completionPct":{"type":"integer"},"locked":{"type":"boolean"}},"required":["sliceId","featureDocsTotal","featureDocsImplemented","featureDocsPartiallyImplemented","featureDocsImplementing","completionPct","locked"]}},"required":["data","facts"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"recomputeSliceStatus","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Recompute a slice's status from its owned feature_docs","description":"Rolls up the slice's owned feature_docs into status + completionPct and returns both the updated row and the derivation facts."}},"/api/v1/services/{serviceId}/tables":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DbTable"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceTables","tags":["Tables"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true},{"in":"query","name":"preseeded","schema":{"type":"string","enum":["true","false"]}}],"summary":"List tables for a service","description":"Includes declaredIn when the repo-relative declaring file has been recorded."},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DbTable"}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Table name already exists for this service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createTable","tags":["Tables"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Add a table to a service","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"schemaText":{"type":"string","minLength":1},"description":{"type":["string","null"]},"declaredIn":{"type":["string","null"],"minLength":1,"maxLength":500},"preseeded":{"type":"boolean"}},"required":["name","schemaText"]}}}}}},"/api/v1/tables/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DbTable"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getTable","tags":["Tables"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a table by id"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DbTable"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateTable","tags":["Tables"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update schema text or description on a table","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"schemaText":{"type":"string","minLength":1},"description":{"type":["string","null"]},"declaredIn":{"type":["string","null"],"minLength":1,"maxLength":500}}}}}}},"delete":{"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"id":{"type":"string","format":"uuid"}},"required":["deleted","id"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Table is locked; pass ?force=true to delete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deleteTable","tags":["Tables"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true},{"in":"query","name":"force","schema":{"type":"string","enum":["true","false"]}}],"summary":"Delete a confirmed-dead/erroneous table row","description":"Hard-deletes the table row — for removing artifacts that no longer exist (dropped tables, erroneous entries). SAFETY GUARD: a locked table (lockedAt IS NOT NULL) is rejected with 409 unless ?force=true is passed, so live/locked contracts can't be accidentally deleted."}},"/api/v1/services/{serviceId}/tables/preseed":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"inserted":{"type":"integer","minimum":0},"skipped":{"type":"integer","minimum":0}},"required":["inserted","skipped"]}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"preseedTables","tags":["Tables"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Bulk preseed tables for a service (idempotent)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"schemaText":{"type":"string","minLength":1},"description":{"type":["string","null"]},"declaredIn":{"type":["string","null"],"minLength":1,"maxLength":500}},"required":["name","schemaText"]},"minItems":1}},"required":["tables"]}}}}}},"/api/v1/tables/{id}/implement":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DbTable"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"implementTable","tags":["Tables"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a table as implemented (shipped in real schema)","description":"Use after the producer service has shipped the table in its real migrations against the local stack per R1. Pairs with contract-lifecycle-progression skill."}},"/api/v1/tables/{id}/deprecate":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DbTable"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deprecateTable","tags":["Tables"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a table as deprecated","description":"Operator action when retiring a table. Replication consumers must migrate off."}},"/api/v1/tables/{id}/lock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DbTable"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"lockTable","tags":["Tables"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Lock a table's contract (freeze the minimum schema)","description":"Sets lockedAt/lockedByAgentId (+ optional lockedBySliceId). Orthogonal to status. Idempotent re-lock.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sliceId":{"type":"string","format":"uuid"}}}}}}}},"/api/v1/tables/{id}/unlock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DbTable"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unlockTable","tags":["Tables"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Unlock a table's contract (operator escape hatch)","description":"Clears lockedAt/lockedByAgentId/lockedBySliceId."}},"/api/v1/services/{serviceId}/sql-lookups":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SqlLookup"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceSqlLookups","tags":["SqlLookups"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["planned","implementing","implemented","deprecated"]},{"type":"array","items":{"type":"string","enum":["planned","implementing","implemented","deprecated"]}}]}}],"summary":"List SQL lookups for a service"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SqlLookup"}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"(serviceId, name) already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createSqlLookup","tags":["SqlLookups"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Add a SQL lookup for a service","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"},"signatureMd":{"type":["string","null"],"maxLength":2048},"bodyMd":{"type":"string"},"status":{"type":"string","enum":["planned","implementing","implemented","deprecated"]}},"required":["name"]}}}}}},"/api/v1/sql-lookups/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SqlLookup"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getSqlLookup","tags":["SqlLookups"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a SQL lookup by id (resolves the long-form body)"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SqlLookup"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateSqlLookup","tags":["SqlLookups"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update a SQL lookup (signature / body / status)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signatureMd":{"type":["string","null"],"maxLength":2048},"bodyMd":{"type":["string","null"]},"status":{"type":"string","enum":["planned","implementing","implemented","deprecated"]}}}}}}}},"/api/v1/sql-lookups/{id}/implement":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SqlLookup"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"implementSqlLookup","tags":["SqlLookups"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a SQL lookup as implemented (shipped in real schema)","description":"Use after the producer service has shipped + tested the optimized lookup against the real backing stack per R1. Pairs with contract-lifecycle-progression skill."}},"/api/v1/sql-lookups/{id}/lock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SqlLookup"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"lockSqlLookup","tags":["SqlLookups"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Lock a SQL lookup's contract (freeze the minimum)","description":"Sets lockedAt/lockedByAgentId (+ optional lockedBySliceId). Orthogonal to status. Idempotent re-lock.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sliceId":{"type":"string","format":"uuid"}}}}}}}},"/api/v1/sql-lookups/{id}/unlock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SqlLookup"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unlockSqlLookup","tags":["SqlLookups"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Unlock a SQL lookup's contract (operator escape hatch)","description":"Clears lockedAt/lockedByAgentId/lockedBySliceId."}},"/api/v1/services/{serviceId}/rest-interfaces":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RestInterfaceWithAliasTarget"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceRestInterfaces","tags":["RestInterfaces"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"List REST endpoints for a service","description":"Alias rows (kind='alias') resolve their target to a compact `aliasTarget` summary; standard rows carry `aliasTarget: null`."},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestInterfaceWithBehavior"}},"required":["data"]}}}},"400":{"description":"Alias-of-alias target (ALIAS_OF_ALIAS)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Service or alias target not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"(method, path) already exists for this service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createRestInterface","tags":["RestInterfaces"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Add a REST endpoint","description":"kind='alias' publishes a gateway re-exposure of another service's standard row (drift 0aa9d095 / D411): aliasTargetId is required, must reference an existing kind='standard' row (no alias-of-alias), and the alias inherits the target's request/response schemas (supplying its own is rejected).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]},"path":{"type":"string","pattern":"^\\/","minLength":1},"requestSchema":{},"responseSchema":{},"agentInvocable":{"type":"boolean"},"operationId":{"type":"string","minLength":1},"behaviorMd":{"type":"string"},"status":{"type":"string","enum":["planned","implemented","deprecated"]},"tier":{"type":"string","enum":["tenant-domain","platform-ops"]},"kind":{"type":"string","enum":["standard","alias"]},"aliasTargetId":{"type":"string","format":"uuid"}},"required":["method","path"]}}}}}},"/api/v1/rest-interfaces/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestInterfaceWithAliasTarget"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getRestInterface","tags":["RestInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a REST interface by id","description":"Alias rows (kind='alias') resolve their target to a compact `aliasTarget` summary; standard rows carry `aliasTarget: null`."},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestInterfaceWithBehavior"}},"required":["data"]}}}},"400":{"description":"Alias rule violation (ALIAS_SELF_REFERENCE / ALIAS_OF_ALIAS / ALIAS_TARGET_REQUIRED / ALIAS_TARGET_ON_STANDARD / ALIAS_SCHEMA_NOT_ALLOWED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found (row or alias target)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Standard row still targeted by aliases (ALIAS_HAS_DEPENDENTS)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateRestInterface","tags":["RestInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update a REST interface (schema / behavior / status / alias)","description":"Alias handling (drift 0aa9d095 / D411): `aliasTargetId` repoints an alias (target must exist, be kind='standard', and differ from the row itself); `kind` converts standard<->alias. Converting to standard auto-clears the pointer; converting to alias requires a target, drops own schemas, and is rejected while other aliases still point at the row.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]},"path":{"type":"string","pattern":"^\\/","minLength":1},"requestSchema":{},"responseSchema":{},"agentInvocable":{"type":"boolean"},"operationId":{"type":["string","null"],"minLength":1},"behaviorMd":{"type":["string","null"]},"status":{"type":"string","enum":["planned","implemented","deprecated"]},"tier":{"type":"string","enum":["tenant-domain","platform-ops"]},"kind":{"type":"string","enum":["standard","alias"]},"aliasTargetId":{"type":["string","null"],"format":"uuid"}}}}}}}},"/api/v1/rest-interfaces/{id}/implement":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestInterface"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"implementRestInterface","tags":["RestInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a REST interface as implemented","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"commitSha":{"type":"string","pattern":"^[0-9a-f]{7,40}$"}}}}}}}},"/api/v1/rest-interfaces/{id}/deprecate":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestInterface"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deprecateRestInterface","tags":["RestInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a REST interface as deprecated"}},"/api/v1/rest-interfaces/{id}/lock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestInterface"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"lockRestInterface","tags":["RestInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Lock a REST endpoint's contract (freeze the minimum)","description":"Sets lockedAt/lockedByAgentId (+ optional lockedBySliceId). Orthogonal to status. Idempotent re-lock.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sliceId":{"type":"string","format":"uuid"}}}}}}}},"/api/v1/rest-interfaces/{id}/unlock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestInterface"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unlockRestInterface","tags":["RestInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Unlock a REST endpoint's contract (operator escape hatch)","description":"Clears lockedAt/lockedByAgentId/lockedBySliceId."}},"/api/v1/grpc-interfaces":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GrpcInterface"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listGrpcInterfaces","tags":["GrpcInterfaces"],"parameters":[{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"agentInvocable","schema":{"type":"string","enum":["true","false"]}},{"in":"query","name":"sagaCallable","schema":{"type":"string","enum":["true","false"]}},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["planned","implemented","deprecated"]},{"type":"array","items":{"type":"string","enum":["planned","implemented","deprecated"]}}]}}],"summary":"Cross-service list of gRPC RPCs"}},"/api/v1/services/{serviceId}/grpc-interfaces":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GrpcInterface"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceGrpcInterfaces","tags":["GrpcInterfaces"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"List gRPC RPCs for a single service"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GrpcInterface"}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"(serviceId, grpcServiceName, rpcName) collides","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createGrpcInterface","tags":["GrpcInterfaces"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Add a gRPC RPC for a service","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"grpcServiceName":{"type":"string","minLength":1},"rpcName":{"type":"string","minLength":1},"requestProto":{"type":"string","minLength":1},"responseProto":{"type":"string","minLength":1},"agentInvocable":{"type":"boolean"},"sagaCallable":{"type":"boolean"},"operationId":{"type":"string","minLength":1},"requiredParams":{},"behaviorMd":{"type":"string"},"status":{"type":"string","enum":["planned","implemented","deprecated"]}},"required":["grpcServiceName","rpcName","requestProto","responseProto"]}}}}}},"/api/v1/grpc-interfaces/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GrpcInterface"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getGrpcInterface","tags":["GrpcInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a gRPC RPC by id"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GrpcInterface"},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateGrpcInterface","tags":["GrpcInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update a gRPC RPC (proto / behavior / flags)","description":"If requestProto or responseProto change AND downstream consumers exist, the response includes a warnings array but the patch is NOT rejected — the operator decides.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"grpcServiceName":{"type":"string","minLength":1},"rpcName":{"type":"string","minLength":1},"requestProto":{"type":"string","minLength":1},"responseProto":{"type":"string","minLength":1},"agentInvocable":{"type":"boolean"},"sagaCallable":{"type":"boolean"},"operationId":{"type":["string","null"],"minLength":1},"requiredParams":{},"behaviorMd":{"type":["string","null"]},"status":{"type":"string","enum":["planned","implemented","deprecated"]}}}}}}}},"/api/v1/grpc-interfaces/{id}/implement":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GrpcInterface"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"implementGrpcInterface","tags":["GrpcInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a gRPC RPC as implemented"}},"/api/v1/grpc-interfaces/{id}/deprecate":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GrpcInterface"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deprecateGrpcInterface","tags":["GrpcInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a gRPC RPC as deprecated"}},"/api/v1/grpc-interfaces/{id}/lock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GrpcInterface"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"lockGrpcInterface","tags":["GrpcInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Lock a gRPC RPC's contract (freeze the minimum for consumers)","description":"Sets lockedAt/lockedByAgentId (+ optional lockedBySliceId). Orthogonal to status — a contract can be locked while still 'planned'. Idempotent: re-locking by the same agent is a 200 no-op that preserves the original lock metadata.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sliceId":{"type":"string","format":"uuid"}}}}}}}},"/api/v1/grpc-interfaces/{id}/unlock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GrpcInterface"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unlockGrpcInterface","tags":["GrpcInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Unlock a gRPC RPC's contract (operator escape hatch)","description":"Clears lockedAt/lockedByAgentId/lockedBySliceId."}},"/api/v1/outbox-topics":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OutboxTopic"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listOutboxTopics","tags":["Outbox"],"parameters":[{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"topicName","schema":{"type":"string"}},{"in":"query","name":"producerLocked","schema":{"type":"string","enum":["true","false"]}}],"summary":"Cross-service list of outbox topics"}},"/api/v1/services/{serviceId}/outbox-topics":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OutboxTopic"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceOutboxTopics","tags":["Outbox"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Outbox topics owned by a service"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OutboxTopic"}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Topic already exists for this service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createOutboxTopic","tags":["Outbox"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Add an outbox topic","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"topicName":{"type":"string","pattern":"^[a-z][a-z0-9_-]+(\\.[a-z0-9_-]+){2,3}\\.v\\d+$|^hr\\.statutory\\.[A-Z0-9]+(?:-(?:[A-Z0-9]+|[a-z][a-z0-9]*))*\\.[a-z0-9_-]+\\.v\\d+$"},"payloadSchema":{},"replicationStrategy":{"type":"string","enum":["bullmq","rpc","redis-streams"]},"description":{"type":["string","null"]},"producerLocked":{"type":"boolean"}},"required":["topicName"]}}}}}},"/api/v1/outbox-topics/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/OutboxTopic"}],"properties":{"consumers":{"type":"array","items":{"$ref":"#/components/schemas/OutboxConsumer"}}},"required":["consumers"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getOutboxTopic","tags":["Outbox"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a topic with embedded consumers"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OutboxTopic"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateOutboxTopic","tags":["Outbox"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update topic schema / strategy","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payloadSchema":{},"replicationStrategy":{"type":"string","enum":["bullmq","rpc","redis-streams"]},"description":{"type":["string","null"]},"producerLocked":{"type":"boolean"}}}}}}},"delete":{"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"id":{"type":"string","format":"uuid"}},"required":["deleted","id"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Topic is producer-locked; pass ?force=true to delete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deleteOutboxTopic","tags":["OutboxTopics"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true},{"in":"query","name":"force","schema":{"type":"string","enum":["true","false"]}}],"summary":"Delete a confirmed-dead/erroneous outbox topic","description":"Hard-deletes the topic row (consumers cascade; outbox service_edges are dropped in the same tx). For removing artifacts that no longer exist — phantom full-prefix topics, retired events. SAFETY GUARD: a producer-locked topic (producerLocked=true) is rejected with 409 unless ?force=true is passed, so live/locked contracts can't be accidentally deleted."}},"/api/v1/outbox-topics/{id}/consumers":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OutboxConsumer"}},"required":["data"]}}}},"404":{"description":"Topic or consumer service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Consumer already subscribed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"subscribeOutboxConsumer","tags":["Outbox"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Subscribe a service to an outbox topic","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"consumerServiceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"handlerDescription":{"type":["string","null"]}},"required":["consumerServiceId"]}}}}}},"/api/v1/outbox-topics/{id}/consumers/{consumerId}":{"delete":{"responses":{"204":{"description":"No content"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unsubscribeOutboxConsumer","tags":["Outbox"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true},{"in":"path","name":"consumerId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Remove a subscription"}},"/api/v1/outbox-topics/{id}/implement":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OutboxTopic"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"implementOutboxTopic","tags":["OutboxTopics"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Lock the outbox topic's producer (mark as implemented)","description":"Sets producerLocked=true. Use after the producer service has shipped the outbox emit code against the real backing stack per R1. Equivalent to a producer-locked-event signal — consumers can now wire against the topic and expect runtime success."}},"/api/v1/outbox-topics/{id}/unlock-producer":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OutboxTopic"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unlockOutboxTopicProducer","tags":["OutboxTopics"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Unlock the outbox topic's producer (revert to in-progress)","description":"Operator-only escape hatch: sets producerLocked=false. Used when a topic needs schema revision after locking. Consumers see this as 'the spec is mutable again'."}},"/api/v1/outbox-topics/{id}/lock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OutboxTopic"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"lockOutboxTopic","tags":["OutboxTopics"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Lock an outbox topic (set producerLocked + lockedAt atomically)","description":"Sets producerLocked=true AND lockedAt/lockedByAgentId (+ optional lockedBySliceId) in one UPDATE. `producerLocked` stays the authoritative gate signal; the lock columns carry uniform metadata. Idempotent re-lock preserves the original timestamp/agent/slice.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sliceId":{"type":"string","format":"uuid"}}}}}}}},"/api/v1/outbox-topics/{id}/unlock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OutboxTopic"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unlockOutboxTopic","tags":["OutboxTopics"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Unlock an outbox topic (clear producerLocked + lock columns)","description":"Clears producerLocked AND lockedAt/lockedByAgentId/lockedBySliceId atomically. Operator escape hatch."}},"/api/v1/approval-kinds":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApprovalKind"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}},"400":{"description":"Invalid filter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listApprovalKinds","tags":["ApprovalKinds"],"parameters":[{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["planned","implementing","implemented","deprecated"]},{"type":"array","items":{"type":"string","enum":["planned","implementing","implemented","deprecated"]}}]}},{"in":"query","name":"domain","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"venue","schema":{"anyOf":[{"type":"string","enum":["home","owning_module","either"]},{"type":"array","items":{"type":"string","enum":["home","owning_module","either"]}}]}},{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}],"summary":"Fleet-wide list of approval kinds (who approves what)","description":"Filter by domain, venue, status and serviceId (each repeatable). D924 §C cl. 13."}},"/api/v1/services/{serviceId}/approval-kinds":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApprovalKind"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}},"400":{"description":"Invalid filter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listServiceApprovalKinds","tags":["ApprovalKinds"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["planned","implementing","implemented","deprecated"]},{"type":"array","items":{"type":"string","enum":["planned","implementing","implemented","deprecated"]}}]}},{"in":"query","name":"domain","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"venue","schema":{"anyOf":[{"type":"string","enum":["home","owning_module","either"]},{"type":"array","items":{"type":"string","enum":["home","owning_module","either"]}}]}}],"summary":"Approval kinds declared by a service","description":"Filter by status, domain and venue (each repeatable)."},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApprovalKind"}},"required":["data"]}}}},"400":{"description":"Invalid declaration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The key is already declared for this service, or its namespace belongs to another service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The key's namespace is reserved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createApprovalKind","tags":["ApprovalKinds"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Declare an approval kind a service raises","description":"Declared `planned` (or `implementing`). The key's first segment is the declaring service's namespace: the first service to declare in a namespace owns it, and the five reserved module keys are refused. `defaultRoute` is the org-node walk (D924 §0); `outcomes` come from D240's vocabulary widened by D924 cl. 16.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*){2,3}$"},"label":{"type":"string","minLength":1},"domain":{"type":"string","pattern":"^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$"},"defaultRoute":{"$ref":"#/components/schemas/ApprovalKindDefaultRoute"},"maxLevels":{"type":["integer","null"],"minimum":1},"previewSchema":{"oneOf":[{"$ref":"#/components/schemas/ApprovalKindPreviewSchema"},{"type":"null"}]},"deferredAction":{"type":["string","null"],"minLength":1},"outcomes":{"type":"array","items":{"type":"string","enum":["approved","rejected","expired","changes_requested","approved_with_cuts"]},"minItems":1},"venue":{"type":"string","enum":["home","owning_module","either"]},"slaDefault":{"oneOf":[{"$ref":"#/components/schemas/ApprovalKindSla"},{"type":"null"}]},"onTimeoutDefault":{"type":["string","null"],"enum":["escalate_next","keep_open_remind_daily","lapse","none",null]},"permissionKey":{"type":"string","pattern":"^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*){2,3}$"},"entitlementKey":{"type":["string","null"],"pattern":"^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$"},"description":{"type":["string","null"]},"status":{"type":"string","enum":["planned","implementing"]}},"required":["key","label","domain","defaultRoute","outcomes","venue","permissionKey"],"additionalProperties":false}}}}}},"/api/v1/approval-kinds/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApprovalKind"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getApprovalKind","tags":["ApprovalKinds"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get an approval kind by id"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApprovalKind"}},"required":["data"]}}}},"400":{"description":"Invalid patch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Not editable in its status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateApprovalKind","tags":["ApprovalKinds"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Edit an approval kind while it is planned or implementing","description":"Any declared column except `key` and `status`. Refused with 409 APPROVAL_KIND_NOT_EDITABLE once the kind is implemented or deprecated.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1},"domain":{"type":"string","pattern":"^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$"},"defaultRoute":{"$ref":"#/components/schemas/ApprovalKindDefaultRoute"},"maxLevels":{"type":["integer","null"],"minimum":1},"previewSchema":{"oneOf":[{"$ref":"#/components/schemas/ApprovalKindPreviewSchema"},{"type":"null"}]},"deferredAction":{"type":["string","null"],"minLength":1},"outcomes":{"type":"array","items":{"type":"string","enum":["approved","rejected","expired","changes_requested","approved_with_cuts"]},"minItems":1},"venue":{"type":"string","enum":["home","owning_module","either"]},"slaDefault":{"oneOf":[{"$ref":"#/components/schemas/ApprovalKindSla"},{"type":"null"}]},"onTimeoutDefault":{"type":["string","null"],"enum":["escalate_next","keep_open_remind_daily","lapse","none",null]},"permissionKey":{"type":"string","pattern":"^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*){2,3}$"},"entitlementKey":{"type":["string","null"],"pattern":"^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$"},"description":{"type":["string","null"]}},"additionalProperties":false}}}}}},"/api/v1/approval-kinds/{id}/mark-implementing":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApprovalKind"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Refused transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"markApprovalKindImplementing","tags":["ApprovalKinds"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"planned → implementing (the producer started building it)","description":"contract-lifecycle-progression. Idempotent on an implementing kind; 409 from implemented or deprecated."}},"/api/v1/approval-kinds/{id}/implement":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApprovalKind"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Refused transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"implementApprovalKind","tags":["ApprovalKinds"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark an approval kind implemented (verified on the real stack)","description":"planned | implementing → implemented, after the raising service proved a real chain end to end (R1). Idempotent; 409 from deprecated."}},"/api/v1/approval-kinds/{id}/deprecate":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApprovalKind"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Refused transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deprecateApprovalKind","tags":["ApprovalKinds"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Deprecate an approval kind (terminal)","description":"Any status → deprecated. Idempotent. Nothing moves a kind out of deprecated."}},"/api/v1/approval-kinds/{id}/lock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApprovalKind"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"lockApprovalKind","tags":["ApprovalKinds"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Lock an approval kind's contract (freeze the declaration)","description":"Sets lockedAt/lockedByAgentId (+ optional lockedBySliceId). Orthogonal to status. Idempotent re-lock keeps the original metadata.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sliceId":{"type":"string","format":"uuid"}}}}}}}},"/api/v1/approval-kinds/{id}/unlock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApprovalKind"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unlockApprovalKind","tags":["ApprovalKinds"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Unlock an approval kind's contract (operator escape hatch)","description":"Clears lockedAt/lockedByAgentId/lockedBySliceId."}},"/api/v1/libraries":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Library"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listLibraries","tags":["Libraries"],"parameters":[],"summary":"List libraries"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Library"}},"required":["data"]}}}},"409":{"description":"Library name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createLibrary","tags":["Libraries"],"parameters":[],"summary":"Create a library record","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"repoUrl":{"type":["string","null"],"format":"uri"},"version":{"type":"string"},"status":{"type":"string","enum":["planned","active","deprecated"]},"description":{"type":["string","null"]}},"required":["name"]}}}}}},"/api/v1/libraries/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Library"}],"properties":{"consumers":{"type":"array","items":{"$ref":"#/components/schemas/ServiceLibraryDep"}}},"required":["consumers"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getLibrary","tags":["Libraries"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a library with its consumers"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Library"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateLibrary","tags":["Libraries"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update version / status / repo","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"repoUrl":{"type":["string","null"],"format":"uri"},"version":{"type":"string"},"status":{"type":"string","enum":["planned","active","deprecated"]},"description":{"type":["string","null"]}}}}}}}},"/api/v1/libraries/{id}/versions":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LibraryVersion"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}},"404":{"description":"Library not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listLibraryVersions","tags":["Libraries"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"List published versions for a library"},"post":{"responses":{"200":{"description":"OK (upserted)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LibraryVersion"}},"required":["data"]}}}},"404":{"description":"Library not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"registerLibraryVersion","tags":["Libraries"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Register a published version for a library","description":"Upserts a version record for the library and syncs `libraries.version` to the registered version. Called by the operator or a libs agent after publishing to npm/pypi/go. Use the `capabilities` field (comma-separated API surface) instead of version strings for capability gates.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","minLength":1},"capabilities":{"type":["string","null"]},"commitSha":{"type":["string","null"]},"publishedAt":{"type":"string","format":"date-time"},"releaseNotes":{"type":["string","null"]}},"required":["version"]}}}}}},"/api/v1/services/{serviceId}/library-deps":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/ServiceLibraryDep"}],"properties":{"library":{"oneOf":[{"$ref":"#/components/schemas/Library"},{"type":"null"}]}},"required":["library"]}},"total":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceLibraryDeps","tags":["Libraries"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"List library deps for a service"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ServiceLibraryDep"}},"required":["data"]}}}},"404":{"description":"Service or library not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Dep already exists — use PATCH instead","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"addLibraryDep","tags":["Libraries"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Add a library dep to a service","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"libraryId":{"type":"string","format":"uuid"},"versionConstraint":{"type":"string","minLength":1}},"required":["libraryId","versionConstraint"]}}}}}},"/api/v1/services/{serviceId}/library-deps/{libId}":{"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ServiceLibraryDep"}},"required":["data"]}}}},"404":{"description":"Dep not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateLibraryDep","tags":["Libraries"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true},{"in":"path","name":"libId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update version constraint","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"versionConstraint":{"type":"string","minLength":1}},"required":["versionConstraint"]}}}}},"delete":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"removed":{"type":"string"}},"required":["removed"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"removeLibraryDep","tags":["Libraries"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true},{"in":"path","name":"libId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Remove a library dep"}},"/api/v1/service-edges":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ServiceEdge"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceEdges","tags":["ServiceEdges"],"parameters":[{"in":"query","name":"from","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"to","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"kind","schema":{"anyOf":[{"type":"string","enum":["grpc","rest","outbox","saga"]},{"type":"array","items":{"type":"string","enum":["grpc","rest","outbox","saga"]}}]}},{"in":"query","name":"status","schema":{"type":"string","enum":["planned","implemented","deprecated"]}}],"summary":"List service edges with filters"}},"/api/v1/services/{serviceId}/edges":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"in":{"type":"array","items":{"$ref":"#/components/schemas/ServiceEdge"}},"out":{"type":"array","items":{"$ref":"#/components/schemas/ServiceEdge"}}},"required":["in","out"]}},"required":["data"]}}}}},"operationId":"getServiceEdgesForService","tags":["ServiceEdges"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true},{"in":"query","name":"direction","schema":{"type":"string","enum":["in","out","both"]}}],"summary":"Edges in/out of a single service"}},"/api/v1/changelog":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChangelogEntry"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listChangelog","tags":["Changelog"],"parameters":[{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"requestHash","schema":{"type":"string","pattern":"^[0-9a-f]{16}$"}},{"in":"query","name":"since","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"until","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"affects","schema":{"type":"string","pattern":"^[a-z_]+:.+$"}},{"in":"query","name":"limit","schema":{"type":"string","pattern":"^\\d+$"}},{"in":"query","name":"offset","schema":{"type":"string","pattern":"^\\d+$"}}],"summary":"List changelog entries with filters"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChangelogEntry"}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"appendChangelog","tags":["Changelog"],"parameters":[],"summary":"Append a changelog entry","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"serviceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"commitSha":{"type":"string","pattern":"^[0-9a-f]{7,40}$"},"summary":{"type":"string","minLength":1},"bodyMd":{"type":["string","null"]},"prUrl":{"type":["string","null"],"format":"uri"},"requestHash":{"type":["string","null"],"pattern":"^[0-9a-f]{16}$"},"affectedArtifacts":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["feature_doc","table","rest_interface","grpc_interface","saga","saga_step","outbox_topic","outbox_consumer","decision","library","library_dep"]},"id":{"type":"string"},"action":{"type":"string","enum":["created","updated","deprecated","deleted","implemented"]}},"required":["kind","id","action"]}}},"required":["serviceId","commitSha","summary"]}}}}}},"/api/v1/services/{serviceId}/changelog":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChangelogEntry"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceChangelog","tags":["Changelog"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true},{"in":"query","name":"requestHash","schema":{"type":"string","pattern":"^[0-9a-f]{16}$"}},{"in":"query","name":"since","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"until","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"affects","schema":{"type":"string","pattern":"^[a-z_]+:.+$"}},{"in":"query","name":"limit","schema":{"type":"string","pattern":"^\\d+$"}},{"in":"query","name":"offset","schema":{"type":"string","pattern":"^\\d+$"}}],"summary":"Changelog entries for a service"}},"/api/v1/changelog/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChangelogEntry"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getChangelogEntry","tags":["Changelog"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a changelog entry by id"}},"/api/v1/health-verdicts":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HealthVerdict"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listHealthVerdicts","tags":["HealthVerdicts"],"parameters":[],"summary":"Latest verdict per service"}},"/api/v1/services/{serviceId}/health-verdicts":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HealthVerdict"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceHealthVerdicts","tags":["HealthVerdicts"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Verdict history for a service"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HealthVerdict"}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postHealthVerdict","tags":["HealthVerdicts"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Post a new verdict for a service","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"verdict":{"type":"string","enum":["good","degraded","bad"]},"reasons":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"artifactType":{"type":"string"},"artifactId":{"type":"string"}},"required":["code","message"]}},"evaluator":{"type":"string","minLength":1}},"required":["verdict","evaluator"]}}}}}},"/api/v1/services/{serviceId}/health":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HealthVerdict"}},"required":["data"]}}}},"404":{"description":"No verdict ever posted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getServiceHealth","tags":["HealthVerdicts"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Latest verdict for a single service"}},"/api/v1/drift":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DriftEntry"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listDrift","tags":["Drift"],"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":500}},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0}},{"in":"query","name":"severity","schema":{"anyOf":[{"type":"string","enum":["local","consumer-visible","breaking"]},{"type":"array","items":{"type":"string","enum":["local","consumer-visible","breaking"]}}]}},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["open","accepted-as-canonical","operator-resolved","superseded"]},{"type":"array","items":{"type":"string","enum":["open","accepted-as-canonical","operator-resolved","superseded"]}}]}},{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"since","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"since_days","schema":{"type":"string","pattern":"^\\d+$"}}],"summary":"Cross-service drift list with filters"}},"/api/v1/services/{serviceId}/drift":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DriftEntry"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceDrift","tags":["Drift"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Drift log for a single service"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DriftEntry"}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"fileDrift","tags":["Drift"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"File a new drift entry","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"severity":{"type":"string","enum":["local","consumer-visible","breaking"]},"summary":{"type":"string","minLength":1},"bodyMd":{"type":"string","minLength":1},"relatedArtifactType":{"type":["string","null"]},"relatedArtifactId":{"type":["string","null"]},"projectId":{"type":["string","null"],"format":"uuid"}},"required":["severity","summary","bodyMd"]}}}}}},"/api/v1/drift/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DriftEntry"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getDrift","tags":["Drift"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a drift entry by id"}},"/api/v1/drift/{id}/accept":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DriftEntry"}},"required":["data"]}}}},"404":{"description":"Drift or decision not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Invalid transition (not in 'open' status)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"acceptDrift","tags":["Drift"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Accept drift as canonical (requires a relatedDecisionId)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"relatedDecisionId":{"type":"string","pattern":"^D\\d+$"},"resolutionMd":{"type":["string","null"]},"newDecision":{"type":"object","properties":{"id":{"type":"string","pattern":"^D\\d+$"},"title":{"type":"string","minLength":1},"bodyMd":{"type":"string","minLength":1},"module":{"type":"string"},"topicTags":{"type":"array","items":{"type":"string"}}},"required":["id","title","bodyMd"]}}}}}}}},"/api/v1/drift/{id}/operator-resolve":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DriftEntry"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Invalid transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"operatorResolveDrift","tags":["Drift"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark drift as operator-resolved","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"resolutionMd":{"type":"string","minLength":1}},"required":["resolutionMd"]}}}}}},"/api/v1/drift/{id}/supersede":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DriftEntry"}},"required":["data"]}}}},"404":{"description":"Drift or superseding drift not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Invalid transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"supersedeDrift","tags":["Drift"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark drift as superseded by another drift entry","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"supersedingDriftId":{"type":"string","format":"uuid"},"resolutionMd":{"type":["string","null"]}},"required":["supersedingDriftId"]}}}}}},"/api/v1/pipelines":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Pipeline"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listPipelines","tags":["Pipelines"],"parameters":[{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"kind","schema":{"anyOf":[{"type":"string","enum":["rpc_mutator","rpc_query","http_webhook","worker_cron","worker_lease"]},{"type":"array","items":{"type":"string","enum":["rpc_mutator","rpc_query","http_webhook","worker_cron","worker_lease"]}}]}},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["planned","implemented","deprecated"]},{"type":"array","items":{"type":"string","enum":["planned","implemented","deprecated"]}}]}},{"in":"query","name":"sagaId","schema":{"type":"string","format":"uuid"}}],"summary":"List pipelines (filter by service, kind, status, saga)"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Pipeline"}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"(serviceId, name) already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Required H1 sections missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createPipeline","tags":["Pipelines"],"parameters":[],"summary":"Create a pipeline","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"serviceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"name":{"type":"string","pattern":"^[a-z][a-z0-9-]*$"},"kind":{"type":"string","enum":["rpc_mutator","rpc_query","http_webhook","worker_cron","worker_lease"]},"trigger":{"type":"string","minLength":1},"grpcInterfaceId":{"type":["string","null"],"format":"uuid"},"restInterfaceId":{"type":["string","null"],"format":"uuid"},"sagaId":{"type":["string","null"],"format":"uuid"},"sagaStepOrder":{"type":["integer","null"],"exclusiveMinimum":0},"bodyMd":{"type":"string","minLength":1},"status":{"type":"string","enum":["planned","implemented","deprecated"]}},"required":["serviceId","name","kind","trigger","bodyMd"]}}}}}},"/api/v1/pipelines/by-key/{serviceId}/{name}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Pipeline"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getPipelineByKey","tags":["Pipelines"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true},{"in":"path","name":"name","schema":{"type":"string","pattern":"^[a-z][a-z0-9-]*$"},"required":true}],"summary":"Get a pipeline by (serviceId, name); body inlined"}},"/api/v1/services/{serviceId}/pipelines":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Pipeline"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServicePipelines","tags":["Pipelines"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"List pipelines for a service"}},"/api/v1/pipelines/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Pipeline"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getPipeline","tags":["Pipelines"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a pipeline by id; body inlined from S3"},"put":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Pipeline"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Required H1 sections missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"replacePipeline","tags":["Pipelines"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Replace a pipeline (full body update)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["rpc_mutator","rpc_query","http_webhook","worker_cron","worker_lease"]},"trigger":{"type":"string","minLength":1},"grpcInterfaceId":{"type":["string","null"],"format":"uuid"},"restInterfaceId":{"type":["string","null"],"format":"uuid"},"sagaId":{"type":["string","null"],"format":"uuid"},"sagaStepOrder":{"type":["integer","null"],"exclusiveMinimum":0},"bodyMd":{"type":"string","minLength":1},"status":{"type":"string","enum":["planned","implemented","deprecated"]}}}}}}},"delete":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Pipeline"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deprecatePipeline","tags":["Pipelines"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Soft-delete (status=deprecated)"}},"/api/v1/doctrine-exceptions":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DoctrineException"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listDoctrineExceptions","tags":["DoctrineExceptions"],"parameters":[{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["active","sunset_planned","revoked"]},{"type":"array","items":{"type":"string","enum":["active","sunset_planned","revoked"]}}]}},{"in":"query","name":"doctrinePath","schema":{"type":"string"}},{"in":"query","name":"decisionId","schema":{"type":"string","pattern":"^([a-z][a-z0-9_-]*-)?D\\d+$"}}],"summary":"List doctrine exceptions"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DoctrineException"}},"required":["data"]}}}},"404":{"description":"Service or doctrine not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Exception already exists for this (service, path, scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Rationale missing required H1 sections, or decision not locked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"fileDoctrineException","tags":["DoctrineExceptions"],"parameters":[],"summary":"File a new doctrine exception","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"serviceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"doctrinePath":{"type":"string","minLength":1},"scope":{"type":"string","minLength":1},"rationaleMd":{"type":"string","minLength":1},"decisionId":{"type":["string","null"],"pattern":"^([a-z][a-z0-9_-]*-)?D\\d+$"},"sunsetTargetDate":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["serviceId","doctrinePath","scope","rationaleMd"]}}}}}},"/api/v1/services/{serviceId}/doctrine-exceptions":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DoctrineException"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceDoctrineExceptions","tags":["DoctrineExceptions"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"All doctrine exceptions for a service"}},"/api/v1/doctrine-exceptions/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DoctrineException"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getDoctrineException","tags":["DoctrineExceptions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a doctrine exception by id; rationale inlined"},"put":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DoctrineException"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Rationale sections missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateDoctrineException","tags":["DoctrineExceptions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update rationale / scope / status","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","minLength":1},"rationaleMd":{"type":"string","minLength":1},"decisionId":{"type":["string","null"],"pattern":"^([a-z][a-z0-9_-]*-)?D\\d+$"},"status":{"type":"string","enum":["active","sunset_planned","revoked"]},"sunsetTargetDate":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}}}}}}},"/api/v1/doctrine-exceptions/{id}/revoke":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DoctrineException"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"revokeDoctrineException","tags":["DoctrineExceptions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Revoke (status → revoked)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"revocationReason":{"type":"string","minLength":1}},"required":["revocationReason"]}}}}}},"/api/v1/doctrine-exceptions/{id}/plan-sunset":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DoctrineException"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"planDoctrineExceptionSunset","tags":["DoctrineExceptions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Plan sunset (status → sunset_planned)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sunsetTargetDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["sunsetTargetDate"]}}}}}},"/api/v1/doctrine/{path}/exceptions":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DoctrineException"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listExceptionsForDoctrinePath","tags":["DoctrineExceptions"],"parameters":[{"in":"path","name":"path","schema":{"type":"string","minLength":1},"required":true}],"summary":"All services diverging from a doctrine path"}},"/api/v1/runbooks":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Runbook"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listRunbooks","tags":["Runbooks"],"parameters":[{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"kind","schema":{"anyOf":[{"type":"string","enum":["local_dev","operations","incident","key_management","compliance","release"]},{"type":"array","items":{"type":"string","enum":["local_dev","operations","incident","key_management","compliance","release"]}}]}},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["active","stale","superseded"]},{"type":"array","items":{"type":"string","enum":["active","stale","superseded"]}}]}}],"summary":"List runbooks"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Runbook"}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"(serviceId, repoRelativePath) already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Required H1 sections missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"registerRunbook","tags":["Runbooks"],"parameters":[],"summary":"Register a runbook","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"serviceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"title":{"type":"string","minLength":1},"kind":{"type":"string","enum":["local_dev","operations","incident","key_management","compliance","release"]},"repoRelativePath":{"type":"string","minLength":1},"summaryMd":{"type":"string","minLength":1}},"required":["serviceId","title","kind","repoRelativePath","summaryMd"]}}}}}},"/api/v1/services/{serviceId}/runbooks":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Runbook"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceRunbooks","tags":["Runbooks"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"All runbooks for a service"}},"/api/v1/runbooks/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Runbook"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getRunbook","tags":["Runbooks"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a runbook; summary inlined"},"put":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Runbook"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Summary missing required H1 sections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateRunbook","tags":["Runbooks"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update a runbook","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1},"kind":{"type":"string","enum":["local_dev","operations","incident","key_management","compliance","release"]},"repoRelativePath":{"type":"string","minLength":1},"summaryMd":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","stale","superseded"]}}}}}}}},"/api/v1/runbooks/{id}/verify":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Runbook"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"verifyRunbook","tags":["Runbooks"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Stamp lastVerifiedAt = now()"}},"/api/v1/runbooks/{id}/mark-stale":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Runbook"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"markRunbookStale","tags":["Runbooks"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a runbook stale","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1}},"required":["reason"]}}}}}},"/api/v1/runbooks/{id}/supersede":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Runbook"}},"required":["data"]}}}},"404":{"description":"Source or replacement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"supersedeRunbook","tags":["Runbooks"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a runbook superseded and link the replacement","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"supersededById":{"type":"string","format":"uuid"}},"required":["supersededById"]}}}}}},"/api/v1/open-questions":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OpenQuestion"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listOpenQuestions","tags":["OpenQuestions"],"parameters":[{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"module","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["open","in_discussion","answered","obsolete"]},{"type":"array","items":{"type":"string","enum":["open","in_discussion","answered","obsolete"]}}]}},{"in":"query","name":"priority","schema":{"anyOf":[{"type":"string","enum":["low","medium","high","blocker"]},{"type":"array","items":{"type":"string","enum":["low","medium","high","blocker"]}}]}},{"in":"query","name":"topicTag","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}],"summary":"List open questions"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OpenQuestion"}},"required":["data"]}}}},"404":{"description":"Service not found (if serviceId set)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Scope required, or context missing required sections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"raiseOpenQuestion","tags":["OpenQuestions"],"parameters":[],"summary":"Raise a new open question","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"serviceId":{"type":["string","null"],"pattern":"^[a-z][a-z0-9_-]*$"},"module":{"type":["string","null"],"minLength":1},"questionMd":{"type":"string","minLength":1},"contextMd":{"type":"string","minLength":1},"topicTags":{"type":"array","items":{"type":"string"},"default":[]},"priority":{"type":"string","enum":["low","medium","high","blocker"],"default":"medium"}},"required":["questionMd"]}}}}}},"/api/v1/services/{serviceId}/open-questions":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OpenQuestion"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceOpenQuestions","tags":["OpenQuestions"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"All open questions for a service"}},"/api/v1/open-questions/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OpenQuestion"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getOpenQuestion","tags":["OpenQuestions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get an open question; context inlined when present"},"put":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OpenQuestion"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Context missing required H1 sections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateOpenQuestion","tags":["OpenQuestions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update question / context / metadata","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"questionMd":{"type":"string","minLength":1},"contextMd":{"type":"string","minLength":1},"topicTags":{"type":"array","items":{"type":"string"}},"priority":{"type":"string","enum":["low","medium","high","blocker"]},"status":{"type":"string","enum":["open","in_discussion","obsolete"]}}}}}}}},"/api/v1/open-questions/{id}/answer":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OpenQuestion"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Already answered, or decision not locked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"answerOpenQuestion","tags":["OpenQuestions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Answer by linking to a locked decision","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"decisionId":{"type":"string","pattern":"^([a-z][a-z0-9_-]*-)?D\\d+$"},"resolutionSummary":{"type":"string"}},"required":["decisionId"]}}}}}},"/api/v1/open-questions/{id}/mark-obsolete":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OpenQuestion"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"markOpenQuestionObsolete","tags":["OpenQuestions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark obsolete (question no longer applies)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1}},"required":["reason"]}}}}}},"/api/v1/skills":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"version":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"name":{"type":"string"},"description":{"type":"string"},"allowedTools":{"type":["string","null"]},"scope":{"type":"string","enum":["global","project"]},"status":{"type":"string","enum":["active","deprecated","superseded"]},"bodyS3Key":{"type":"string"},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"repoUrl":{"type":["string","null"]},"supersedesId":{"type":["string","null"],"format":"uuid"},"projectSlug":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","slug","version","name","description","allowedTools","scope","status","bodyS3Key","bodySha256","bodyBytes","repoUrl","supersedesId","projectSlug","createdByAgentId","createdAt","updatedAt"]}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listSkills","tags":["Skills"],"parameters":[{"in":"query","name":"scope","schema":{"type":"string","enum":["global","project"]}},{"in":"query","name":"status","schema":{"type":"string","enum":["active","deprecated","superseded"]}},{"in":"query","name":"projectSlug","schema":{"type":"string"}}],"summary":"List skills"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"version":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"name":{"type":"string"},"description":{"type":"string"},"allowedTools":{"type":["string","null"]},"scope":{"type":"string","enum":["global","project"]},"status":{"type":"string","enum":["active","deprecated","superseded"]},"bodyS3Key":{"type":"string"},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"repoUrl":{"type":["string","null"]},"supersedesId":{"type":["string","null"],"format":"uuid"},"projectSlug":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","slug","version","name","description","allowedTools","scope","status","bodyS3Key","bodySha256","bodyBytes","repoUrl","supersedesId","projectSlug","createdByAgentId","createdAt","updatedAt"]}},"required":["data"]}}}},"409":{"description":"Slug already has an active version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createSkill","tags":["Skills"],"parameters":[],"summary":"Register a new skill (v1)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z][a-z0-9-]*$","minLength":2},"name":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"allowedTools":{"type":["string","null"]},"scope":{"type":"string","enum":["global","project"]},"projectSlug":{"type":["string","null"]},"repoUrl":{"type":["string","null"],"format":"uri"},"bodyMd":{"type":"string","minLength":1}},"required":["slug","name","description","bodyMd"]}}}}}},"/api/v1/skills/slugs":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}}},"required":["data"]}}}}},"operationId":"listSkillSlugs","tags":["Skills"],"parameters":[],"summary":"List active skill slugs (lightweight bootstrap check)"}},"/api/v1/skills/by-slug/{slug}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"version":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"name":{"type":"string"},"description":{"type":"string"},"allowedTools":{"type":["string","null"]},"scope":{"type":"string","enum":["global","project"]},"status":{"type":"string","enum":["active","deprecated","superseded"]},"bodyS3Key":{"type":"string"},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"repoUrl":{"type":["string","null"]},"supersedesId":{"type":["string","null"],"format":"uuid"},"projectSlug":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","slug","version","name","description","allowedTools","scope","status","bodyS3Key","bodySha256","bodyBytes","repoUrl","supersedesId","projectSlug","createdByAgentId","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getSkillBySlug","tags":["Skills"],"parameters":[{"in":"path","name":"slug","schema":{"type":"string","minLength":1},"required":true}],"summary":"Get latest active version of a skill by slug"}},"/api/v1/skills/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"version":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"name":{"type":"string"},"description":{"type":"string"},"allowedTools":{"type":["string","null"]},"scope":{"type":"string","enum":["global","project"]},"status":{"type":"string","enum":["active","deprecated","superseded"]},"bodyS3Key":{"type":"string"},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"repoUrl":{"type":["string","null"]},"supersedesId":{"type":["string","null"],"format":"uuid"},"projectSlug":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","slug","version","name","description","allowedTools","scope","status","bodyS3Key","bodySha256","bodyBytes","repoUrl","supersedesId","projectSlug","createdByAgentId","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getSkillById","tags":["Skills"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a skill by UUID"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"version":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"name":{"type":"string"},"description":{"type":"string"},"allowedTools":{"type":["string","null"]},"scope":{"type":"string","enum":["global","project"]},"status":{"type":"string","enum":["active","deprecated","superseded"]},"bodyS3Key":{"type":"string"},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"repoUrl":{"type":["string","null"]},"supersedesId":{"type":["string","null"],"format":"uuid"},"projectSlug":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","slug","version","name","description","allowedTools","scope","status","bodyS3Key","bodySha256","bodyBytes","repoUrl","supersedesId","projectSlug","createdByAgentId","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"patchSkillMeta","tags":["Skills"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update skill metadata without creating a new body revision","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"repoUrl":{"type":["string","null"],"format":"uri"}}}}}}}},"/api/v1/skills/{id}/body":{"get":{"responses":{"200":{"description":"Markdown body","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getSkillBody","tags":["Skills"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Download skill body markdown from S3"}},"/api/v1/skills/{id}/revise":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"version":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"name":{"type":"string"},"description":{"type":"string"},"allowedTools":{"type":["string","null"]},"scope":{"type":"string","enum":["global","project"]},"status":{"type":"string","enum":["active","deprecated","superseded"]},"bodyS3Key":{"type":"string"},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"repoUrl":{"type":["string","null"]},"supersedesId":{"type":["string","null"],"format":"uuid"},"projectSlug":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","slug","version","name","description","allowedTools","scope","status","bodyS3Key","bodySha256","bodyBytes","repoUrl","supersedesId","projectSlug","createdByAgentId","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Skill not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"reviseSkill","tags":["Skills"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Create a new version of a skill","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"allowedTools":{"type":["string","null"]},"repoUrl":{"type":["string","null"],"format":"uri"},"bodyMd":{"type":"string","minLength":1}},"required":["bodyMd"]}}}}}},"/api/v1/skills/{id}/deprecate":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"version":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"name":{"type":"string"},"description":{"type":"string"},"allowedTools":{"type":["string","null"]},"scope":{"type":"string","enum":["global","project"]},"status":{"type":"string","enum":["active","deprecated","superseded"]},"bodyS3Key":{"type":"string"},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"repoUrl":{"type":["string","null"]},"supersedesId":{"type":["string","null"],"format":"uuid"},"projectSlug":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","slug","version","name","description","allowedTools","scope","status","bodyS3Key","bodySha256","bodyBytes","repoUrl","supersedesId","projectSlug","createdByAgentId","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deprecateSkill","tags":["Skills"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a skill as deprecated"}},"/api/v1/runners":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Runner"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listRunners","tags":["Runners"],"parameters":[{"in":"query","name":"serviceId","schema":{"type":"string"}},{"in":"query","name":"kind","schema":{"type":"string","enum":["agent-runner","orchestrator"]}},{"in":"query","name":"status","schema":{"type":"string","enum":["online","degraded","offline"]}}],"summary":"List registered runners","description":"Filterable by serviceId / kind / status. Ordered by freshest heartbeat first."},"post":{"responses":{"200":{"description":"Refreshed an existing runner","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Runner"}},"required":["data"]}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Runner"}},"required":["data"]}}}}},"operationId":"registerRunner","tags":["Runners"],"parameters":[],"summary":"Register or refresh a runner","description":"Idempotent upsert on the (kind, serviceId, baseUrl) identity (NULLS NOT DISTINCT). Re-registering the same box refreshes its version/status/heartbeat. Returns 201 when freshly created, 200 when an existing row was refreshed.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunnerRegister"}}}}}},"/api/v1/runners/{id}/heartbeat":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Runner"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"runnerHeartbeat","tags":["Runners"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Bump a runner's heartbeat","description":"Bumps last_heartbeat_at and optionally sets status. No audit row (high-frequency), mirroring agents/:id/heartbeat.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["online","degraded","offline"]}}}}}}}},"/api/v1/runners/{id}/usage":{"post":{"responses":{"200":{"description":"Upserted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UsageCeiling"}},"required":["data"]}}}},"404":{"description":"Unknown runner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"api_credit reported by a non-orchestrator runner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postRunnerUsage","tags":["Runners"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Report a runner's usage-ceiling state","description":"Upserts the runner's state for one ceiling on the (runnerId, ceiling) key. `subscription` is valid for any runner; `api_credit` is valid ONLY for kind=orchestrator (impl boxes report subscription only) — an api_credit report from a non-orchestrator runner is rejected 422 USAGE_CEILING_NOT_APPLICABLE. Audited as runner.usage_report.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunnerUsageReport"}}}}}},"/api/v1/routing/lookup":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RoutingHit"}},"required":["data"]}}}},"400":{"description":"Bad key form (zero or more than one)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Target not found, or no runner owns it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unsupported artifact type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"routingLookup","tags":["Routing"],"parameters":[{"in":"query","name":"sliceId","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"}},{"in":"query","name":"artifactType","schema":{"type":"string","enum":["grpc_interface","rest_interface","table","outbox_topic","saga","sql_lookup","grpc","rest","outbox","sql"]}},{"in":"query","name":"artifactId","schema":{"type":"string","format":"uuid"}}],"summary":"Resolve the runner that owns a routing target","description":"Open read. Supply EXACTLY ONE of sliceId, serviceId, or (artifactType + artifactId). Returns the freshest non-offline runner's baseUrl + status for the producing service plus its active implementer agent."}},"/api/v1/usage":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UsageFanInRunner"}},"total":{"type":"number"}},"required":["data","total"]}}}}},"operationId":"getUsageFanIn","tags":["Usage"],"parameters":[{"in":"query","name":"serviceId","schema":{"type":"string"}},{"in":"query","name":"state","schema":{"type":"string","enum":["ok","warning","exhausted"]}}],"summary":"Operator fan-in of every runner's usage ceilings","description":"Open read. Returns each runner with its current usage ceilings, grouped per runner. Filterable by serviceId (runners driving that service) and state (only ceilings in that state; runners with no matching ceiling are excluded)."}},"/api/v1/notification-types":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NotificationType"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listNotificationTypes","tags":["Notification registry"],"parameters":[],"summary":"List the 12 notification types (D947 §2)"}},"/api/v1/notification-events":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NotificationEvent"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listNotificationEvents","tags":["Notification registry"],"parameters":[{"in":"query","name":"status","schema":{"type":"string","enum":["proposed","approved","built","retired"]}},{"in":"query","name":"typeKey","schema":{"type":"string"}},{"in":"query","name":"producerServiceId","schema":{"type":"string"}},{"in":"query","name":"channel","schema":{"type":"string","enum":["email","sms","whatsapp","voice","push","in_app","oob"]}},{"in":"query","name":"emailRoute","schema":{"type":"string","enum":["nodii_only","prefer_tenant","prefer_tenant_guarded","none","provider_under_test"]}},{"in":"query","name":"includeRevisions","schema":{"type":"string","enum":["true","false"]}}],"summary":"List notification events (live revision per key by default)"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationEvent"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"422","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"proposeNotificationEvent","tags":["Notification registry"],"parameters":[],"summary":"Propose a new notification event","description":"Any producer service (or the operator) may propose. Status is always `proposed`; a request is filed to nodii-notification-service.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationEventPropose"}}}}}},"/api/v1/notification-events/export":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NotificationEvent"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}},"text/csv":{"schema":{"type":"string"}}}}},"operationId":"exportNotificationEvents","tags":["Notification registry"],"parameters":[{"in":"query","name":"format","schema":{"type":"string","enum":["json","csv"],"default":"json"}}],"summary":"Export every revision as JSON or CSV"}},"/api/v1/notification-events/by-key/{eventKey}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"current":{"$ref":"#/components/schemas/NotificationEvent"},"revisions":{"type":"array","items":{"$ref":"#/components/schemas/NotificationEvent"}}},"required":["current","revisions"]}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getNotificationEventByKey","tags":["Notification registry"],"parameters":[{"in":"path","name":"eventKey","schema":{"type":"string","minLength":1,"maxLength":200},"required":true}],"summary":"Get the live revision of an event key plus its history"}},"/api/v1/notification-events/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationEvent"}},"required":["data"]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getNotificationEvent","tags":["Notification registry"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get one notification event revision by id"}},"/api/v1/notification-events/{id}/revise":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationEvent"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"422","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"reviseNotificationEvent","tags":["Notification registry"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Append a new proposed revision of an event","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationEventRevise"}}}}}},"/api/v1/notification-events/{id}/approve":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationEvent"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"422","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"approveNotificationEvent","tags":["Notification registry"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Approve a proposed event and rule its mute/billing/email route","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationEventApprove"}}}}}},"/api/v1/notification-events/{id}/mark-built":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationEvent"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"422","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"markNotificationEventBuilt","tags":["Notification registry"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Record template keys + commit SHA for an approved event","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationEventMarkBuilt"}}}}}},"/api/v1/notification-events/{id}/retire":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationEvent"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"422","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"retireNotificationEvent","tags":["Notification registry"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Retire an event (needs replacedBy or a reason)","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationEventRetire"}}}}}},"/api/v1/workers":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Worker"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listWorkers","tags":["Workers"],"parameters":[{"in":"query","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"}},{"in":"query","name":"kind","schema":{"type":"string","enum":["cron","sweeper","consumer","saga-runner","outbox-drainer","queue-worker","reconciler","other"]}},{"in":"query","name":"status","schema":{"type":"string","enum":["planned","implementing","partially_implemented","implemented","deprecated"]}},{"in":"query","name":"processIsolation","schema":{"type":"string","enum":["compliant","non_compliant","unknown"]}},{"in":"query","name":"ratification","schema":{"type":"string","enum":["unratified","ratified","disputed"]}},{"in":"query","name":"tenancy","schema":{"type":"string","enum":["per-tenant","global"]}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":1000,"default":200}},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0}}],"summary":"List workers fleet-wide (filterable, paginated)","description":"Rows include contractRefs, ackBehavior and retryBackoff when recorded by the owning service."}},"/api/v1/workers/summary":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkerServiceSummary"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"getWorkersSummary","tags":["Workers"],"parameters":[],"summary":"Per-service worker counts by process isolation + ratification"}},"/api/v1/workers/by-key/{workerKey}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Worker"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getWorkerByKey","tags":["Workers"],"parameters":[{"in":"path","name":"workerKey","schema":{"type":"string","minLength":1,"maxLength":200},"required":true}],"summary":"Get a worker by its fleet-unique workerKey"}},"/api/v1/workers/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Worker"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getWorker","tags":["Workers"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a worker by id"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Worker"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateWorker","tags":["Workers"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Edit a worker's descriptive fields (owner or operator)","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkerPatch"}}}}},"delete":{"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"id":{"type":"string","format":"uuid"}},"required":["deleted","id"]}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deleteWorker","tags":["Workers"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true},{"in":"query","name":"force","schema":{"type":"string","enum":["true","false"]}}],"summary":"Delete a worker (owner or operator; ratified rows need ?force=true)"}},"/api/v1/services/{serviceId}/workers":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Worker"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listServiceWorkers","tags":["Workers"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"List the workers of one service"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Worker"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createWorker","tags":["Workers"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Register a worker for a service","description":"Owner service or operator only. Provenance is always `service`. An agent of the owning service lands the row `ratified` (a service registering its own worker ratifies it); an operator-created row lands `unratified` until the owner ratifies it.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkerCreate"}}}}}},"/api/v1/services/{serviceId}/workers/preseed":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkerPreseedResult"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"preseedWorkers","tags":["Workers"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Hub-scan pre-fill of a service's workers (operator only)","description":"One transaction. New keys insert as provenance=hub-scan, unratified. An existing unratified hub-scan row of the same service is refreshed; service-owned, ratified or disputed rows are skipped; a key owned by another service is skipped and reported in `conflicts`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkerPreseed"}}}}}},"/api/v1/workers/{id}/status":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Worker"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"setWorkerStatus","tags":["Workers"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Set a worker's lifecycle status (owner or operator)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["planned","implementing","partially_implemented","implemented","deprecated"]}},"required":["status"],"additionalProperties":false}}}}}},"/api/v1/workers/{id}/ratify":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Worker"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"ratifyWorker","tags":["Workers"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Ratify a worker row (owning service or operator only)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":4000}},"additionalProperties":false}}}}}},"/api/v1/workers/{id}/dispute":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Worker"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"disputeWorker","tags":["Workers"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Dispute a worker row (owning service or operator only)","description":"Stores `reason` (plus the JSON of `corrections`, if given) in `ratificationNote` and flips ratification to `disputed`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkerDispute"}}}}}},"/api/v1/issues":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Issue"}},"total":{"type":"integer","minimum":0},"nextCursor":{"type":["string","null"]}},"required":["data","total","nextCursor"]}}}}},"operationId":"listIssues","tags":["Issues"],"parameters":[{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Filter by owning service (repeatable)"}},{"in":"query","name":"project","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["todo","in_progress","in_review","blocked","done","wont_do"]},{"type":"array","items":{"type":"string","enum":["todo","in_progress","in_review","blocked","done","wont_do"]}}]}},{"in":"query","name":"kind","schema":{"anyOf":[{"type":"string","enum":["feature","bug","chore","drift","request","verification"]},{"type":"array","items":{"type":"string","enum":["feature","bug","chore","drift","request","verification"]}}]}},{"in":"query","name":"priority","schema":{"anyOf":[{"type":"string","enum":["p0","p1","p2","p3"]},{"type":"array","items":{"type":"string","enum":["p0","p1","p2","p3"]}}]}},{"in":"query","name":"claimed","schema":{"type":"string","enum":["true","false"],"description":"true = live lease only; false = unclaimed"}},{"in":"query","name":"claimedBy","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":500}},{"in":"query","name":"cursor","schema":{"type":"string","maxLength":200}}],"summary":"List issues (newest first, keyset cursor)","description":"Filters: serviceId, project, status, kind, priority (each repeatable), claimed (live lease), claimedBy. Pass `nextCursor` back as `cursor`."},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IssueDetail"}},"required":["data"]}}}},"409":{"description":"Key already taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unknown service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createIssue","tags":["Issues"],"parameters":[],"summary":"File an issue against a service","description":"Key defaults to `<PROJECT>-<n>` (or a service-derived prefix) with n = 1 + the highest numeric suffix in use. New issues start in `todo`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"serviceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"title":{"type":"string","minLength":1,"maxLength":300},"bodyMd":{"type":"string","maxLength":200000},"kind":{"type":"string","enum":["feature","bug","chore","drift","request","verification"]},"priority":{"type":"string","enum":["p0","p1","p2","p3"]},"project":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9_-]{0,39}$"},"source":{"type":"string","enum":["manual","backlog_import","drift","request","ticket"]},"sourceRef":{"type":"string","maxLength":500},"links":{"$ref":"#/components/schemas/IssueLinks"},"key":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9._-]{0,99}$","description":"Explicit key; default `<PROJECT|SERVICE>-<n>`"},"onBehalfOf":{"type":"string","minLength":1,"maxLength":200}},"required":["serviceId","title"]}}}}}},"/api/v1/issues/{ref}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IssueDetail"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getIssue","tags":["Issues"],"parameters":[{"in":"path","name":"ref","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"},"required":true}],"summary":"Get an issue (by uuid or key) with body, events and lease state"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IssueDetail"}},"required":["data"]}}}},"403":{"description":"Lease held by another agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateIssue","tags":["Issues"],"parameters":[{"in":"path","name":"ref","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"},"required":true}],"summary":"Edit an issue's title / body / kind / priority / project / links","description":"Status changes go through POST /issues/:ref/transition. While another agent holds a live lease only that holder (or the operator) may edit.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"bodyMd":{"type":"string","maxLength":200000},"kind":{"type":"string","enum":["feature","bug","chore","drift","request","verification"]},"priority":{"type":"string","enum":["p0","p1","p2","p3"]},"project":{"type":["string","null"],"pattern":"^[A-Za-z][A-Za-z0-9_-]{0,39}$"},"links":{"$ref":"#/components/schemas/IssueLinks"},"onBehalfOf":{"type":"string","minLength":1,"maxLength":200}}}}}}}},"/api/v1/issues/{ref}/transition":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IssueDetail"}},"required":["data"]}}}},"403":{"description":"Lease held by another agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Illegal transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"transitionIssue","tags":["Issues"],"parameters":[{"in":"path","name":"ref","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"},"required":true}],"summary":"Move an issue along the enforced status map","description":"todo→{in_progress,blocked,done,wont_do}; in_progress→{in_review,blocked,todo,done,wont_do}; in_review→{in_progress,blocked,done,wont_do}; blocked→{todo,in_progress,wont_do}; done→todo; wont_do→todo. Closing (done/wont_do) ends any lease. Illegal moves return 409 ISSUE_ILLEGAL_TRANSITION with the allowed set. Set releaseClaim=true to release the current lease in the same transaction; staff need devops.issues.write, and an agent may release only its own claim.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","enum":["todo","in_progress","in_review","blocked","done","wont_do"]},"note":{"type":"string","maxLength":10000},"releaseClaim":{"type":"boolean","const":true,"description":"Release the current issue claim atomically"},"releaseReason":{"type":"string","minLength":1,"maxLength":10000,"description":"Optional audit reason for releasing the claim"},"onBehalfOf":{"type":"string","minLength":1,"maxLength":200}},"required":["to"]}}}}}},"/api/v1/issues/{ref}/claim":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IssueDetail"}},"required":["data"]}}}},"403":{"description":"agentId differs from the signer (non-operator)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Lease held by another agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Issue is closed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"claimIssue","tags":["Issues"],"parameters":[{"in":"path","name":"ref","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"},"required":true}],"summary":"Lease an issue for an agent acting on behalf of a person","description":"Refused with 409 LEASE_HELD while another agent's lease is live; an expired lease may be taken over. Claiming a `todo` issue moves it to `in_progress`. Default TTL 30 min, max 24 h; renew via heartbeat.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid","description":"Defaults to the signing agent; operator may claim for another"},"onBehalfOf":{"type":"string","minLength":1,"maxLength":200,"description":"The named person this agent acts for (D1367 §1)"},"ttlMinutes":{"type":"integer","exclusiveMinimum":0,"maximum":1440}},"required":["onBehalfOf"]}}}}}},"/api/v1/issues/{ref}/heartbeat":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IssueDetail"}},"required":["data"]}}}},"403":{"description":"Lease not held by this agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"heartbeatIssue","tags":["Issues"],"parameters":[{"in":"path","name":"ref","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"},"required":true}],"summary":"Renew the caller's lease on an issue","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ttlMinutes":{"type":"integer","exclusiveMinimum":0,"maximum":1440}}}}}}}},"/api/v1/issues/{ref}/release":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IssueDetail"}},"required":["data"]}}}},"403":{"description":"Lease not held by this agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"releaseIssue","tags":["Issues"],"parameters":[{"in":"path","name":"ref","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"},"required":true}],"summary":"Release a lease without closing the issue","description":"Holder or operator only. An `in_progress` issue returns to `todo`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":10000},"onBehalfOf":{"type":"string","minLength":1,"maxLength":200}}}}}}}},"/api/v1/issues/{ref}/comment":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IssueEvent"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"commentOnIssue","tags":["Issues"],"parameters":[{"in":"path","name":"ref","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"},"required":true}],"summary":"Append a comment to an issue's activity feed","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":10000},"onBehalfOf":{"type":"string","minLength":1,"maxLength":200}},"required":["body"]}}}}}},"/api/v1/backlogs":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Backlog"}],"properties":{"itemCount":{"type":"integer"}},"required":["itemCount"]}},"total":{"type":"integer"}},"required":["data","total"]}}}}},"operationId":"listBacklogs","tags":["Backlogs"],"parameters":[{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"project","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}],"summary":"List backlogs with item counts"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BacklogDetail"}},"required":["data"]}}}},"409":{"description":"Slug taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unknown service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createBacklog","tags":["Backlogs"],"parameters":[],"summary":"Create a named, ordered backlog for a service or project","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,62}$"},"name":{"type":"string","minLength":1,"maxLength":200},"serviceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"project":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9_-]{0,39}$"},"description":{"type":"string","maxLength":2000}},"required":["slug","name"]}}}}}},"/api/v1/backlogs/{ref}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BacklogDetail"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getBacklog","tags":["Backlogs"],"parameters":[{"in":"path","name":"ref","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9-]{0,99}$"},"required":true}],"summary":"Get a backlog (by uuid or slug) with its items in order"}},"/api/v1/backlogs/{ref}/items":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BacklogDetail"}},"required":["data"]}}}},"404":{"description":"Backlog or issue not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Already in this backlog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Anchor not in this backlog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"addBacklogItem","tags":["Backlogs"],"parameters":[{"in":"path","name":"ref","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9-]{0,99}$"},"required":true}],"summary":"Add an issue to a backlog (appended unless anchored)","description":"Positions are gap integers (1024 apart), renumbered when a gap closes.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"issueId":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$","description":"Issue uuid or key"},"beforeIssueId":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"},"afterIssueId":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"}},"required":["issueId"]}}}}}},"/api/v1/backlogs/{ref}/items/{issueRef}/move":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BacklogDetail"}},"required":["data"]}}}},"404":{"description":"Backlog / issue / item not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Anchor not in this backlog, or anchor is the item itself","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"moveBacklogItem","tags":["Backlogs"],"parameters":[{"in":"path","name":"ref","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9-]{0,99}$"},"required":true},{"in":"path","name":"issueRef","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"},"required":true}],"summary":"Move an item directly before or after another item","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"beforeIssueId":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"},"afterIssueId":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"}}}}}}}},"/api/v1/backlogs/{ref}/items/{issueRef}":{"delete":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BacklogDetail"}},"required":["data"]}}}},"404":{"description":"Backlog / issue / item not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"removeBacklogItem","tags":["Backlogs"],"parameters":[{"in":"path","name":"ref","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9-]{0,99}$"},"required":true},{"in":"path","name":"issueRef","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"},"required":true}],"summary":"Remove an issue from a backlog (the issue itself is kept)"}},"/api/v1/services/{id}/work":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ServiceWorkSummary"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getServiceWork","tags":["Issues"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Open issues by status, live claims, and the oldest open issue"}},"/api/v1/builds":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BuildView"}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listBuilds","tags":["Delivery"],"parameters":[{"in":"query","name":"serviceId","schema":{"type":"string"}},{"in":"query","name":"environment","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string"}},{"in":"query","name":"blocked","schema":{"type":"string","enum":["true","false"]}},{"in":"query","name":"since","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"cursor","schema":{"type":"string","maxLength":200}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":200}}],"summary":"List builds (deploy runs), newest first","description":"Filters: serviceId, environment, status (deploy status), blocked, since (started at or after), comma-separated for multi-value. Keyset paged: pass the returned nextCursor back as cursor."}},"/api/v1/builds/summary":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BuildSummary"}}},"required":["data"]}}}}},"operationId":"getBuildSummary","tags":["Delivery"],"parameters":[],"summary":"Summarize all builds by service and environment","description":"Returns the latest build and CI/deploy status counts computed over the complete build history."}},"/api/v1/builds/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BuildDetail"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getBuild","tags":["Delivery"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a build with the changes it carries"}},"/api/v1/builds/report":{"post":{"responses":{"200":{"description":"Updated an existing build","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Build"}},"required":["data"]}}}},"201":{"description":"Recorded a new build","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Build"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"repo / runId disagree with runUrl or the service's repo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"reportBuild","tags":["Delivery"],"parameters":[],"summary":"Report a deploy run (nodii-infra deploy workflow)","description":"Idempotent upsert keyed by (repo, runId); repo and runId are read from runUrl when omitted and must agree with it. Carries the image digest the poller cannot see (request 7c4c76bd).","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildReport"}}}}}},"/api/v1/changes":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChangeView"}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listChanges","tags":["Delivery"],"parameters":[{"in":"query","name":"serviceId","schema":{"type":"string"}},{"in":"query","name":"mark","schema":{"type":"string"}},{"in":"query","name":"since","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"touches","schema":{"type":"string","enum":["proto","openapi","migration","outbox-contract","rbac-catalog","frontend","docs-only","ci-only","tests-only"]}},{"in":"query","name":"userVisible","schema":{"type":"string","enum":["true","false"]}},{"in":"query","name":"cursor","schema":{"type":"string","maxLength":200}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":200}}],"summary":"List changes (merged PRs), newest merge first","description":"Filters: serviceId, mark (comma-separated), since (merged at or after), touches (one classifier tag), userVisible. Keyset paged via nextCursor."}},"/api/v1/changes/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChangeDetail"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getChange","tags":["Delivery"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a change with the builds that shipped it and its paths"}},"/api/v1/changes/{id}/mark":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Change"}},"required":["data"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Reason missing, or fixedByChangeId invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"markChange","tags":["Delivery"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a change verified / broken / rolled back","description":"Staff need devops.releases.verify to mark Verified; other marks and userVisible changes need devops.changes.write. A reason is required for broken and rolled_back. fixedByChangeId (only with broken) names the change that fixes it: a build carrying both is not blocked. Every call is audited as change.mark with the previous and new values.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeMarkInput"}}}}}},"/api/v1/services/{serviceId}/delivery":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ServiceDelivery"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getServiceDelivery","tags":["Delivery"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Delivery summary: last build per environment, change counts"}},"/api/v1/delivery/poll-state":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryPollState"}}},"required":["data"]}}}}},"operationId":"listDeliveryPollState","tags":["Delivery"],"parameters":[],"summary":"The GitHub poller's per-repo high-water marks and last errors"}},"/api/v1/runtime":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RuntimeObservation"}}},"required":["data"]}}}}},"operationId":"listRuntimeInventory","tags":["Runtime"],"parameters":[],"summary":"List the latest runtime inventory across the fleet"}},"/api/v1/services/{id}/runtime":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RuntimeObservation"}}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getServiceRuntime","tags":["Runtime"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"List the latest runtime inventory for a service"}},"/api/v1/lanes/summary":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"count":{"type":"number"}},"required":["status","kind","count"]}}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getLaneSummary","tags":["Lanes"],"parameters":[],"summary":"Count lanes by phase and kind"}},"/api/v1/lanes":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"stuck":{"type":"boolean"}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt","stuck"]}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listLanes","tags":["Lanes"],"parameters":[{"in":"query","name":"kind","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string"}},{"in":"query","name":"machine","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"agent","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"waiting-on","schema":{"type":"string","enum":["backend","frontend"]}},{"in":"query","name":"stuck","schema":{"type":"string","enum":["true","false"]}},{"in":"query","name":"cursor","schema":{"type":"string","maxLength":500}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"summary":"List lanes with cursor pagination"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createLane","tags":["Lanes"],"parameters":[],"summary":"Create a queued lane and workflow steps","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","pattern":"^[A-Z][A-Z0-9]*-[0-9]+$"},"title":{"type":"string","minLength":1,"maxLength":500},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string","minLength":1},"minItems":1},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string","minLength":1},"worktree":{"type":"string","minLength":1},"issueIds":{"type":"array","items":{"type":"string","format":"uuid"},"default":[]},"stepLimitSeconds":{"type":"integer","exclusiveMinimum":0,"maximum":604800},"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"required":["key","title","kind","side","repos","agentId","machineId","branch","worktree"]}}}}}},"/api/v1/lanes/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"stuck":{"type":"boolean"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"laneId":{"type":"string","format":"uuid"},"side":{"type":"string","enum":["backend","frontend","both"]},"stepKey":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"state":{"type":"string","enum":["waiting","current","done","blocked"]},"startedAt":{"type":["string","null"]},"completedAt":{"type":["string","null"]},"blockedAt":{"type":["string","null"]}},"required":["id","laneId","side","stepKey","label","position","state","startedAt","completedAt","blockedAt"]}},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"laneId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["lane_started","step_started","step_done","step_blocked","evidence","heartbeat","stuck","escalated","prioritized","deprioritized","stopped","acknowledged"]},"actorAgentId":{"type":["string","null"],"format":"uuid"},"actorRef":{"type":["string","null"]},"actorPersonId":{"type":["string","null"]},"via":{"type":"string"},"metadata":{"type":"object","additionalProperties":{}},"episodeKey":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","laneId","type","actorAgentId","actorRef","actorPersonId","via","metadata","episodeKey","createdAt"]}},"issues":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"}},"required":["id","key","title"]}},"acknowledgement":{"type":["object","null"],"properties":{"laneId":{"type":"string","format":"uuid"},"acknowledgedByAgentId":{"type":["string","null"],"format":"uuid"},"acknowledgedByPersonId":{"type":["string","null"]},"note":{"type":["string","null"]},"acknowledgedAt":{"type":"string"}},"required":["laneId","acknowledgedByAgentId","acknowledgedByPersonId","note","acknowledgedAt"]}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt","stuck","steps","events","issues","acknowledgement"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getLane","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Z][A-Z0-9]*-[0-9]+$"}]},"required":true}],"summary":"Get lane steps and timeline"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateLane","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Z][A-Z0-9]*-[0-9]+$"}]},"required":true}],"summary":"Update editable lane fields","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":500},"repos":{"type":"array","items":{"type":"string","minLength":1},"minItems":1},"agentId":{"type":"string","format":"uuid"},"branch":{"type":"string","minLength":1},"worktree":{"type":"string","minLength":1},"issueIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"additionalProperties":false}}}}}},"/api/v1/lanes/{id}/start":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"startLane","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Z][A-Z0-9]*-[0-9]+$"}]},"required":true}],"summary":"Start a queued lane","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"default":{"via":"nodii-dev"}}}}}}},"/api/v1/lanes/{id}/steps/{stepId}/done":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"laneId":{"type":"string","format":"uuid"},"side":{"type":"string","enum":["backend","frontend","both"]},"stepKey":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"state":{"type":"string","enum":["waiting","current","done","blocked"]},"startedAt":{"type":["string","null"]},"completedAt":{"type":["string","null"]},"blockedAt":{"type":["string","null"]}},"required":["id","laneId","side","stepKey","label","position","state","startedAt","completedAt","blockedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"completeLaneStep","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Z][A-Z0-9]*-[0-9]+$"}]},"required":true},{"in":"path","name":"stepId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Complete the current lane step","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"default":{"via":"nodii-dev"}}}}}}},"/api/v1/lanes/{id}/steps/{stepId}/block":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"laneId":{"type":"string","format":"uuid"},"side":{"type":"string","enum":["backend","frontend","both"]},"stepKey":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"state":{"type":"string","enum":["waiting","current","done","blocked"]},"startedAt":{"type":["string","null"]},"completedAt":{"type":["string","null"]},"blockedAt":{"type":["string","null"]}},"required":["id","laneId","side","stepKey","label","position","state","startedAt","completedAt","blockedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"blockLaneStep","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Z][A-Z0-9]*-[0-9]+$"}]},"required":true},{"in":"path","name":"stepId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Block the current lane step","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"default":{"via":"nodii-dev"}}}}}}},"/api/v1/lanes/{id}/steps/{stepId}/start":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"laneId":{"type":"string","format":"uuid"},"side":{"type":"string","enum":["backend","frontend","both"]},"stepKey":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"state":{"type":"string","enum":["waiting","current","done","blocked"]},"startedAt":{"type":["string","null"]},"completedAt":{"type":["string","null"]},"blockedAt":{"type":["string","null"]}},"required":["id","laneId","side","stepKey","label","position","state","startedAt","completedAt","blockedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"startLaneStep","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Z][A-Z0-9]*-[0-9]+$"}]},"required":true},{"in":"path","name":"stepId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Start or resume a lane step","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"default":{"via":"nodii-dev"}}}}}}},"/api/v1/lanes/{id}/evidence":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"stuck":{"type":"boolean"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"laneId":{"type":"string","format":"uuid"},"side":{"type":"string","enum":["backend","frontend","both"]},"stepKey":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"state":{"type":"string","enum":["waiting","current","done","blocked"]},"startedAt":{"type":["string","null"]},"completedAt":{"type":["string","null"]},"blockedAt":{"type":["string","null"]}},"required":["id","laneId","side","stepKey","label","position","state","startedAt","completedAt","blockedAt"]}},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"laneId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["lane_started","step_started","step_done","step_blocked","evidence","heartbeat","stuck","escalated","prioritized","deprioritized","stopped","acknowledged"]},"actorAgentId":{"type":["string","null"],"format":"uuid"},"actorRef":{"type":["string","null"]},"actorPersonId":{"type":["string","null"]},"via":{"type":"string"},"metadata":{"type":"object","additionalProperties":{}},"episodeKey":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","laneId","type","actorAgentId","actorRef","actorPersonId","via","metadata","episodeKey","createdAt"]}},"issues":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"}},"required":["id","key","title"]}},"acknowledgement":{"type":["object","null"],"properties":{"laneId":{"type":"string","format":"uuid"},"acknowledgedByAgentId":{"type":["string","null"],"format":"uuid"},"acknowledgedByPersonId":{"type":["string","null"]},"note":{"type":["string","null"]},"acknowledgedAt":{"type":"string"}},"required":["laneId","acknowledgedByAgentId","acknowledgedByPersonId","note","acknowledgedAt"]}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt","stuck","steps","events","issues","acknowledgement"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"addLaneEvidence","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Z][A-Z0-9]*-[0-9]+$"}]},"required":true}],"summary":"Append lane evidence","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["pr","commit","figma_frame","deploy","dev_check"]},"url":{"type":"string","format":"uri"},"ref":{"type":"string","minLength":1},"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"required":["kind"]}}}}}},"/api/v1/lanes/{id}/heartbeat":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"stuck":{"type":"boolean"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"laneId":{"type":"string","format":"uuid"},"side":{"type":"string","enum":["backend","frontend","both"]},"stepKey":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"state":{"type":"string","enum":["waiting","current","done","blocked"]},"startedAt":{"type":["string","null"]},"completedAt":{"type":["string","null"]},"blockedAt":{"type":["string","null"]}},"required":["id","laneId","side","stepKey","label","position","state","startedAt","completedAt","blockedAt"]}},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"laneId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["lane_started","step_started","step_done","step_blocked","evidence","heartbeat","stuck","escalated","prioritized","deprioritized","stopped","acknowledged"]},"actorAgentId":{"type":["string","null"],"format":"uuid"},"actorRef":{"type":["string","null"]},"actorPersonId":{"type":["string","null"]},"via":{"type":"string"},"metadata":{"type":"object","additionalProperties":{}},"episodeKey":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","laneId","type","actorAgentId","actorRef","actorPersonId","via","metadata","episodeKey","createdAt"]}},"issues":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"}},"required":["id","key","title"]}},"acknowledgement":{"type":["object","null"],"properties":{"laneId":{"type":"string","format":"uuid"},"acknowledgedByAgentId":{"type":["string","null"],"format":"uuid"},"acknowledgedByPersonId":{"type":["string","null"]},"note":{"type":["string","null"]},"acknowledgedAt":{"type":"string"}},"required":["laneId","acknowledgedByAgentId","acknowledgedByPersonId","note","acknowledgedAt"]}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt","stuck","steps","events","issues","acknowledgement"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"heartbeatLane","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Z][A-Z0-9]*-[0-9]+$"}]},"required":true}],"summary":"Heartbeat a lane","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":500},"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"default":{"via":"nodii-dev"}}}}}}},"/api/v1/lanes/{id}/land":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"landLane","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Z][A-Z0-9]*-[0-9]+$"}]},"required":true}],"summary":"Record that lane work reached main","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"default":{"via":"nodii-dev"}}}}}}},"/api/v1/lanes/{id}/review":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"reviewLane","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Z][A-Z0-9]*-[0-9]+$"}]},"required":true}],"summary":"Move built lane into review","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"default":{"via":"nodii-dev"}}}}}}},"/api/v1/lanes/{id}/verify":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"verifyLaneOnDev","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Z][A-Z0-9]*-[0-9]+$"}]},"required":true}],"summary":"Verify lane on dev with dev-check evidence","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"ref":{"type":"string","minLength":1},"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}}}}}}}},"/api/v1/lanes/{id}/prioritize":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"prioritizeLane","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Z][A-Z0-9]*-[0-9]+$"}]},"required":true}],"summary":"prioritize lane","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500},"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"required":["reason"]}}}}}},"/api/v1/lanes/{id}/deprioritize":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deprioritizeLane","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Z][A-Z0-9]*-[0-9]+$"}]},"required":true}],"summary":"deprioritize lane","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500},"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"required":["reason"]}}}}}},"/api/v1/lanes/{id}/stop":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"stopLane","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Z][A-Z0-9]*-[0-9]+$"}]},"required":true}],"summary":"Stop a lane as the operator","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":4000},"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"required":["reason"]}}}}}},"/api/v1/built":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"acknowledgement":{"type":["object","null"],"properties":{"laneId":{"type":"string","format":"uuid"},"acknowledgedByAgentId":{"type":["string","null"],"format":"uuid"},"acknowledgedByPersonId":{"type":["string","null"]},"note":{"type":["string","null"]},"acknowledgedAt":{"type":"string"}},"required":["laneId","acknowledgedByAgentId","acknowledgedByPersonId","note","acknowledgedAt"]}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt","acknowledgement"]}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listBuiltLanes","tags":["Lanes"],"parameters":[{"in":"query","name":"cursor","schema":{"type":"string","maxLength":500}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"in":"query","name":"includeAcknowledged","schema":{"type":"string","enum":["true","false"],"default":"false"}}],"summary":"List built lanes with cursor pagination"}},"/api/v1/built/{id}/acknowledge":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"laneId":{"type":"string","format":"uuid"},"acknowledgedByAgentId":{"type":["string","null"],"format":"uuid"},"acknowledgedByPersonId":{"type":["string","null"]},"note":{"type":["string","null"]},"acknowledgedAt":{"type":"string"}},"required":["laneId","acknowledgedByAgentId","acknowledgedByPersonId","note","acknowledgedAt"]}}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"acknowledgeBuiltLane","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Z][A-Z0-9]*-[0-9]+$"}]},"required":true}],"summary":"Acknowledge one on-dev lane","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":["string","null"],"maxLength":4000},"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}}}}}}}},"/api/v1/built/acknowledge":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"laneId":{"type":"string","format":"uuid"},"acknowledgedByAgentId":{"type":["string","null"],"format":"uuid"},"acknowledgedByPersonId":{"type":["string","null"]},"note":{"type":["string","null"]},"acknowledgedAt":{"type":"string"}},"required":["laneId","acknowledgedByAgentId","acknowledgedByPersonId","note","acknowledgedAt"]}}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"bulkAcknowledgeBuiltLanes","tags":["Lanes"],"parameters":[],"summary":"Acknowledge on-dev lanes in bulk","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":["string","null"],"maxLength":4000},"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"},"laneIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":200}},"required":["laneIds"]}}}}}},"/api/v1/machines":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Machine"}},"total":{"type":"number"}},"required":["data","total"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listMachines","tags":["Lanes"],"parameters":[],"summary":"List machines"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Machine"}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createMachine","tags":["Lanes"],"parameters":[],"summary":"Create a machine with its coordinator","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"coordinatorAgentId":{"type":"string","format":"uuid"},"heavySlotTotal":{"type":"integer","exclusiveMinimum":0,"maximum":128,"default":1},"hostFacts":{"type":"object","additionalProperties":{},"default":{}},"memoryFacts":{"type":"object","additionalProperties":{},"default":{}}},"required":["name","coordinatorAgentId"]}}}}}},"/api/v1/machines/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getMachine","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a machine, agents, and lanes"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Machine"}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateMachine","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update machine facts and capacity","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"heavySlotTotal":{"type":"integer","exclusiveMinimum":0,"maximum":128,"default":1},"hostFacts":{"type":"object","additionalProperties":{},"default":{}},"memoryFacts":{"type":"object","additionalProperties":{},"default":{}}},"additionalProperties":false}}}}}},"/api/v1/machines/{id}/agents":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"assignAgentToMachine","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Assign an agent and home repository to a machine","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"},"homeRepo":{"type":"string","minLength":1,"maxLength":300}},"required":["agentId","homeRepo"]}}}}}},"/api/v1/machines/{id}/report":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Machine"}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"reportMachine","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Report machine resources","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"hostFacts":{"type":"object","additionalProperties":{}},"memoryFacts":{"type":"object","additionalProperties":{}},"heavySlotTotal":{"type":"integer","exclusiveMinimum":0,"maximum":128}},"required":["hostFacts","memoryFacts","heavySlotTotal"]}}}}}},"/api/v1/machines/{id}/coordinator":{"put":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Machine"}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"setMachineCoordinator","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Set the machine's sole coordinator","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"}},"required":["agentId"]}}}}}},"/api/v1/services/{id}/gate":{"get":{"responses":{"200":{"description":"Gate verdict"}},"operationId":"getServiceGate","tags":["Inbox"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}]}},"/api/v1/gate":{"get":{"responses":{"200":{"description":"Fleet gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FleetGateResponse"}}}}},"operationId":"getFleetGate","tags":["Inbox"],"parameters":[]}},"/api/v1/gate/dry-run":{"get":{"responses":{"200":{"description":"Enforcement dry run"}},"operationId":"getGateDryRun","tags":["Inbox"],"parameters":[]}},"/api/v1/inbox":{"get":{"responses":{"200":{"description":"Merged FIFO inbox"}},"operationId":"listInbox","tags":["Inbox"],"parameters":[{"in":"query","name":"serviceId","schema":{"type":"string","minLength":1},"required":true},{"in":"query","name":"kind","schema":{"type":"string","enum":["drift","request","question","lane_escalation"]},"required":false},{"in":"query","name":"cursor","schema":{"type":"string"},"required":false},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false}]}},"/api/v1/inbox/{kind}/{id}/answer":{"post":{"responses":{"200":{"description":"Answered"}},"operationId":"answerInboxItem","tags":["Inbox"],"parameters":[{"in":"path","name":"kind","schema":{"type":"string","enum":["drift","request","question","lane_escalation"]},"required":true},{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"bodyMd":{"type":"string","minLength":1},"onBehalfOf":{"type":"string","minLength":1}},"required":["bodyMd"]}}}}}},"/api/v1/inbox/{kind}/{id}/assign":{"post":{"responses":{"200":{"description":"Assigned"},"409":{"description":"Project started"}},"operationId":"assignInboxItem","tags":["Inbox"],"parameters":[{"in":"path","name":"kind","schema":{"type":"string","enum":["drift","request","question","lane_escalation"]},"required":true},{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"reason":{"type":"string","minLength":1},"notifyService":{"type":"boolean"}},"required":["projectId","reason","notifyService"]}}}}}},"/api/v1/inbox/{kind}/{id}/rule":{"post":{"responses":{"201":{"description":"Decision locked and item resolved"}},"operationId":"ruleInboxItemIntoDecision","tags":["Inbox"],"parameters":[{"in":"path","name":"kind","schema":{"type":"string","enum":["drift","request","question","lane_escalation"]},"required":true},{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"object","properties":{"id":{"type":"string","pattern":"^([a-z][a-z0-9_-]*-)?D\\d+$"},"title":{"type":"string","minLength":1},"module":{"type":"string","minLength":1},"bodyMd":{"type":"string","minLength":1},"topicTags":{"type":"array","items":{"type":"string"},"default":[]}},"required":["id","title","module","bodyMd"]},"amends":{"type":"array","items":{"type":"string"}},"resolutionMd":{"type":"string","minLength":1}},"required":["decision","resolutionMd"]}}}}}},"/api/v1/refresher/{serviceId}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"type":"object"}}}}},"operationId":"getServiceRefresher","tags":["Composite"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true},{"in":"query","name":"include_audit","schema":{"type":"string","enum":["true","false"]}},{"in":"query","name":"changelog_limit","schema":{"type":"string","pattern":"^\\d+$"}},{"in":"query","name":"drift_limit","schema":{"type":"string","pattern":"^\\d+$"}}],"summary":"Single-call hydration: everything an agent needs to start working on a service","description":"Parallel query plan. Returns service + health + doctrine + decisions + feature docs + tables + REST/gRPC + sagas + outbox + approval kinds + libs + requests + drift + recent changelog + edges."}},"/api/v1/impact/{artifactType}/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Unsupported artifact type","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Artifact not found","content":{"application/json":{"schema":{"type":"object"}}}}},"operationId":"getImpact","tags":["Composite"],"parameters":[{"in":"path","name":"artifactType","schema":{"type":"string","enum":["grpc_interface","rest_interface","outbox_topic","table","saga","decision","library","approval_kind"]},"required":true},{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"What depends on this artifact?"}},"/api/v1/search":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Empty query","content":{"application/json":{"schema":{"type":"object"}}}}},"operationId":"search","tags":["Composite"],"parameters":[{"in":"query","name":"q","schema":{"type":"string","minLength":1},"required":true},{"in":"query","name":"kind","schema":{"anyOf":[{"type":"string","enum":["decision","doctrine","feature_doc","rest_interface","grpc_interface"]},{"type":"array","items":{"type":"string","enum":["decision","doctrine","feature_doc","rest_interface","grpc_interface"]}}]},"required":false},{"in":"query","name":"serviceId","schema":{"type":"string"},"required":false},{"in":"query","name":"limit","schema":{"type":"string","pattern":"^\\d+$"},"required":false}],"summary":"Full-text search across decisions, doctrine, feature docs, REST + gRPC"}},"/api/v1/services/{serviceId}/unblock-surface":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"type":"object"}}}}},"operationId":"getUnblockSurface","tags":["Composite"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"What is blocking this service? One call returns all open drift, requests, open questions, and a next-action recommendation per item.","description":"Composite read that replaces the 5-query Python coordinator sweep. All items are open/unresolved only. Sorted breaking→consumer-visible→local for drift, oldest-first for requests."}}},"security":[{"oauth":[]}]}
1
+ {"openapi":"3.1.0","info":{"title":"Nodii Dev API","version":"0.1.0","description":"Dev, reached only through the platform edge at /devops/api/v1/* with a nodii-auth OAuth bearer (the platform tenant's nodii-dev app, D1368)."},"servers":[{"url":"https://platform.nucleus-cloud.in/devops"}],"components":{"securitySchemes":{"oauth":{"type":"http","scheme":"bearer","description":"nodii-auth OAuth access token"}},"schemas":{"HealthResponse":{"type":"object","properties":{"status":{"type":"string","const":"ok"},"at":{"type":"string"},"rbacCatalog":{"type":"object","properties":{"domainKey":{"type":"string"},"catalogVersion":{"type":"string"},"status":{"type":"string","enum":["disabled","pending","published","degraded"]},"attempts":{"type":"integer","minimum":0}},"required":["domainKey","catalogVersion","status","attempts"]}},"required":["status","at","rbacCatalog"]},"Service":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"wave":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["planned","feature_docs_drafting","contracts_authoring","scaffolding","implementing","partially_implemented","implemented","live","active","deprecated","frozen"]},"owner":{"type":["string","null"]},"repoUrl":{"type":["string","null"]},"description":{"type":["string","null"]},"activeImplementerAgentId":{"type":["string","null"],"format":"uuid"},"lastImplSessionAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","wave","status","owner","repoUrl","description","activeImplementerAgentId","lastImplSessionAt","createdAt","updatedAt"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"boolean","const":true},"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["error","code"]},"ServiceInsert":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"name":{"type":"string"},"wave":{"type":"integer","minimum":0,"maximum":5},"status":{"type":"string","enum":["planned","feature_docs_drafting","contracts_authoring","scaffolding","implementing","partially_implemented","implemented","live","active","deprecated","frozen"]},"owner":{"type":["string","null"]},"repoUrl":{"type":["string","null"]},"description":{"type":["string","null"]},"activeImplementerAgentId":{"type":["string","null"],"format":"uuid"},"lastImplSessionAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","wave"]},"ServiceStatusFacts":{"type":"object","properties":{"serviceId":{"type":"string"},"featureDocsTotal":{"type":"number"},"featureDocsImplemented":{"type":"number"},"featureDocsPartiallyImplemented":{"type":"number"},"featureDocsImplementing":{"type":"number"},"contractsTotal":{"type":"number"},"hasActiveImplementer":{"type":"boolean"}},"required":["serviceId","featureDocsTotal","featureDocsImplemented","featureDocsPartiallyImplemented","featureDocsImplementing","contractsTotal","hasActiveImplementer"]},"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sessionId":{"type":"string"},"serviceId":{"type":["string","null"]},"name":{"type":"string"},"personId":{"type":["string","null"]},"oauthAppClientId":{"type":["string","null"]},"oauthAppInstallationId":{"type":["string","null"]},"appGrantPermissionKeys":{"type":"array","items":{"type":"string"}},"machineId":{"type":["string","null"],"format":"uuid"},"role":{"type":"string","enum":["coordinator","agent"]},"homeRepo":{"type":["string","null"]},"laneLimit":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["active","idle","disconnected"]},"heartbeatIntervalSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"authenticationMethod":{"type":"string"},"lastSeenAt":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","sessionId","serviceId","name","personId","oauthAppClientId","oauthAppInstallationId","appGrantPermissionKeys","machineId","role","homeRepo","laneLimit","status","heartbeatIntervalSeconds","authenticationMethod","lastSeenAt","createdAt"]},"AgentRegister":{"type":"object","properties":{"sessionId":{"type":"string"},"serviceId":{"type":["string","null"]},"name":{"type":"string"},"oauthAppClientId":{"type":["string","null"]},"oauthAppInstallationId":{"type":["string","null"]},"heartbeatIntervalSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"authenticationMethod":{"type":"string"},"lastSeenAt":{"type":"string"},"createdAt":{"type":"string"}},"required":["sessionId","name"]},"AgentWakeupResult":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"at":{"type":"string"},"status":{"type":"string","enum":["in_progress","compiling","testing","awaiting_review","blocked","complete","released","failed-validation"]},"commitSha":{"type":["string","null"]},"notes":{"type":["string","null"]},"nextWakeupHint":{"type":["string","null"],"enum":["normal","fast","slow","awaiting-external",null]}},"required":["id","agentId","at","status","commitSha","notes","nextWakeupHint"]},"GlobalDoctrine":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"path":{"type":"string"},"version":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"title":{"type":"string"},"kind":{"type":"string","enum":["global","workflow","module"]},"scope":{"type":["string","null"]},"enforcement":{"type":["string","null"]},"decisionRefs":{"type":"array","items":{"type":"string"}},"bodyS3Key":{"type":"string"},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"sourceSha":{"type":["string","null"]},"supersedesId":{"type":["string","null"],"format":"uuid"},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"era":{"type":"string","enum":["pre-dev","ad"]},"createdAt":{"type":"string"},"deprecatedAt":{"type":["string","null"]},"deprecatedReason":{"type":["string","null"]},"deprecatedByAgentId":{"type":["string","null"],"format":"uuid"}},"required":["id","path","version","title","kind","scope","enforcement","decisionRefs","bodyS3Key","bodySha256","bodyBytes","sourceSha","supersedesId","createdByAgentId","era","createdAt","deprecatedAt","deprecatedReason","deprecatedByAgentId"]},"Decision":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"module":{"type":"string"},"topicTags":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["pending","locked","superseded"]},"bodyS3Key":{"type":"string"},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"supersedesId":{"type":["string","null"]},"supersededById":{"type":["string","null"]},"lockedAt":{"type":["string","null"]},"era":{"type":"string","enum":["pre-dev","ad"]},"decisionNumber":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"adKind":{"type":["string","null"],"enum":["ruling","ratification",null]},"contextMd":{"type":["string","null"]},"optionsMd":{"type":["string","null"]},"rulingMd":{"type":["string","null"]},"consequencesMd":{"type":["string","null"]},"provenanceMd":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","title","module","topicTags","status","bodyS3Key","bodySha256","bodyBytes","supersedesId","supersededById","lockedAt","era","decisionNumber","adKind","contextMd","optionsMd","rulingMd","consequencesMd","provenanceMd","createdAt","updatedAt"]},"DecisionAmendment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"decisionId":{"type":"string"},"amendedByDecisionId":{"type":"string"},"noteMd":{"type":"string"},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"}},"required":["id","decisionId","amendedByDecisionId","noteMd","createdByAgentId","createdAt"]},"FeatureDoc":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"docKey":{"type":"string"},"version":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"title":{"type":"string"},"area":{"type":["string","null"]},"decisionRefs":{"type":"array","items":{"type":"string"}},"bodyS3Key":{"type":"string"},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["planned","approved","implementing","partially_implemented","implemented","superseded"]},"claimedByAgentId":{"type":["string","null"],"format":"uuid"},"claimExpiresAt":{"type":["string","null"]},"completionPct":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"shippedAt":{"type":["string","null"]},"implementationCommitSha":{"type":["string","null"]},"supersedesId":{"type":["string","null"],"format":"uuid"},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"era":{"type":"string","enum":["pre-dev","ad"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","docKey","version","title","area","decisionRefs","bodyS3Key","bodySha256","bodyBytes","status","claimedByAgentId","claimExpiresAt","completionPct","shippedAt","implementationCommitSha","supersedesId","createdByAgentId","era","createdAt","updatedAt"]},"Saga":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"orchestratorServiceId":{"type":"string"},"descriptionS3Key":{"type":"string"},"descriptionSha256":{"type":"string"},"descriptionBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["planned","implemented","deprecated"]},"lockedAt":{"type":["string","null"]},"lockedByAgentId":{"type":["string","null"],"format":"uuid"},"lockedBySliceId":{"type":["string","null"],"format":"uuid"},"reconciliationState":{"type":"string","enum":["clean","dirty"]},"reconciledAt":{"type":["string","null"]},"reconciledByAgentId":{"type":["string","null"],"format":"uuid"},"dirtyReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","orchestratorServiceId","descriptionS3Key","descriptionSha256","descriptionBytes","status","lockedAt","lockedByAgentId","lockedBySliceId","reconciliationState","reconciledAt","reconciledByAgentId","dirtyReason","createdAt","updatedAt"]},"SagaStep":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sagaId":{"type":"string","format":"uuid"},"stepOrder":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"callsServiceId":{"type":"string"},"callsRpc":{"type":"string"},"compensationRpc":{"type":["string","null"]},"sync":{"type":"boolean"},"description":{"type":["string","null"]}},"required":["id","sagaId","stepOrder","callsServiceId","callsRpc","compensationRpc","sync","description"]},"Request":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"requestHash":{"type":"string"},"fromService":{"type":"string"},"toService":{"type":"string"},"kind":{"type":"string"},"specMd":{"type":"string"},"targetArtifactType":{"type":["string","null"]},"targetArtifactId":{"type":["string","null"]},"status":{"type":"string","enum":["open","acknowledged","resolved","rejected"]},"resolvedCommitSha":{"type":["string","null"]},"resolutionMd":{"type":["string","null"]},"relatedDecisionId":{"type":["string","null"]},"shippedVersion":{"type":["string","null"]},"parentRequestId":{"type":["string","null"],"format":"uuid"},"specSummary":{"type":["string","null"]},"requiredCapability":{"type":["string","null"]},"claimedByAgentId":{"type":["string","null"],"format":"uuid"},"claimExpiresAt":{"type":["string","null"]},"expiresAt":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"resolvedByAgentId":{"type":["string","null"],"format":"uuid"},"resolvedAt":{"type":["string","null"]},"era":{"type":"string","enum":["pre-dev","ad"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","requestHash","fromService","toService","kind","specMd","targetArtifactType","targetArtifactId","status","resolvedCommitSha","resolutionMd","relatedDecisionId","shippedVersion","parentRequestId","specSummary","requiredCapability","claimedByAgentId","claimExpiresAt","expiresAt","createdByAgentId","resolvedByAgentId","resolvedAt","era","createdAt","updatedAt"]},"AuditLog":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"actor":{"type":"string"},"action":{"type":"string"},"targetKind":{"type":"string"},"targetId":{"type":["string","null"]},"payload":{},"truncated":{"type":"boolean"},"requestId":{"type":["string","null"]},"at":{"type":"string"}},"required":["id","actor","action","targetKind","targetId","truncated","requestId","at"]},"CronTick":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"at":{"type":"string"},"payload":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},{"type":"object","additionalProperties":{}},{"type":"array","items":{}},{"type":"null"}]}},"required":["id","name","at","payload"]},"CronTickInsert":{"type":"object","properties":{"name":{"type":"string"},"payload":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},{"type":"object","additionalProperties":{}},{"type":"array","items":{}},{"type":"null"}]}},"required":["name"]},"CredentialExpiry":{"type":"object","properties":{"name":{"type":"string"},"setAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"daysLeft":{"type":["integer","null"]},"status":{"type":"string","enum":["ok","warning","critical","expired","unconfigured","invalid"]},"alerts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"threshold":{"type":"string","enum":["14d","3d","expired"]},"title":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"firedAt":{"type":"string","format":"date-time"},"acknowledgedAt":{"type":["string","null"],"format":"date-time"},"acknowledgedBy":{"type":["string","null"]}},"required":["id","threshold","title","expiresAt","firedAt","acknowledgedAt","acknowledgedBy"]}}},"required":["name","setAt","expiresAt","daysLeft","status","alerts"]},"ReconciledContract":{"type":"object","additionalProperties":{}},"AdDocumentSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"docPath":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["principles","methodology","standard","doctrine","ux-guideline","know-how","feature-doc","service-overview","capability-plan"]},"kindLabel":{"type":"string"},"section":{"type":"string"},"serviceId":{"type":["string","null"]},"domain":{"type":"string"},"owner":{"type":"string"},"status":{"type":"string","enum":["draft","ratified"]},"currentVersion":{"type":"string"},"era":{"type":"string","enum":["pre-dev","ad"]},"incorporates":{"type":"array","items":{"type":"string"}},"groundedAt":{"type":["string","null"]},"clauseCount":{"type":"integer"},"parkedCount":{"type":"integer"},"parkedPending":{"type":"boolean"},"domainEra":{"type":"string","enum":["pre-dev","ad"]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"string"}]}},"required":["id","code","docPath","title","kind","kindLabel","section","serviceId","domain","owner","status","currentVersion","era","incorporates","groundedAt","clauseCount","parkedCount","parkedPending","domainEra","updatedAt"]},"ParkedAcknowledgement":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"docCode":{"type":"string"},"documentId":{"type":["string","null"],"format":"uuid"},"title":{"type":"string"},"count":{"type":"integer"},"itemsSha256":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"line":{"type":"integer"}},"required":["text","line"]}},"status":{"type":"string","enum":["pending","acknowledged"]},"requestedAt":{"anyOf":[{"type":"string"},{"type":"string"}]},"requestedByLabel":{"type":"string"},"acknowledgedAt":{"anyOf":[{"type":"string"},{"type":"string"},{"type":"null"}]},"acknowledgedByLabel":{"type":["string","null"]}},"required":["id","docCode","documentId","title","count","itemsSha256","items","status","requestedAt","requestedByLabel","acknowledgedAt","acknowledgedByLabel"]},"AdDocumentUpload":{"type":"object","properties":{"documents":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","maxLength":1024},"content":{"type":"string","minLength":1,"maxLength":2000000},"changeClass":{"type":"string","enum":["ruling","conformance","editorial"]},"baseVersion":{"type":["string","null"],"pattern":"^\\d{1,4}(\\.\\d{1,4})?$"},"conformanceRef":{"type":"string","minLength":1,"maxLength":500},"meaningUnchangedReason":{"type":"string","minLength":1,"maxLength":4000}},"required":["content","changeClass","baseVersion"]},"minItems":1,"maxItems":500},"decision":{"$ref":"#/components/schemas/AdDecisionInput"}},"required":["documents"]},"AdDecisionInput":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"context":{"type":"string","minLength":1,"maxLength":50000},"options":{"type":"string","minLength":1,"maxLength":50000},"ruling":{"type":"string","minLength":1,"maxLength":50000},"consequences":{"type":"string","minLength":1,"maxLength":50000},"provenance":{"type":"string","minLength":1,"maxLength":50000},"amends":{"type":"array","items":{"type":"object","properties":{"docCode":{"type":"string","pattern":"^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*$"},"clauseId":{"type":["string","null"],"minLength":1,"maxLength":100},"effect":{"type":"string","enum":["adds","replaces","narrows","extends","retires"]}},"required":["docCode","effect"]},"maxItems":2000}},"required":["title","context","options","ruling","consequences","provenance","amends"]},"AdDecision":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer"},"title":{"type":"string"},"kind":{"type":"string","enum":["ruling","ratification"]},"status":{"type":"string"},"context":{"type":"string"},"options":{"type":"string"},"ruling":{"type":"string"},"consequences":{"type":"string"},"provenance":{"type":"string"},"amends":{"type":"array","items":{"type":"object","properties":{"docCode":{"type":"string"},"clauseId":{"type":["string","null"]},"effect":{"type":"string","enum":["adds","replaces","narrows","extends","retires"]},"documentId":{"type":"string","format":"uuid"},"documentTitle":{"type":"string"},"version":{"type":"string"},"previousVersion":{"type":["string","null"]}},"required":["docCode","clauseId","effect","documentId","documentTitle","version","previousVersion"]}},"lockedAt":{"anyOf":[{"type":"string"},{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"string"}]},"era":{"type":"string","enum":["pre-dev","ad"]}},"required":["id","number","title","kind","status","context","options","ruling","consequences","provenance","amends","lockedAt","createdAt","era"]},"AdDomain":{"type":"object","properties":{"key":{"type":"string"},"kind":{"type":"string","enum":["rulebook-section","doctrine","service"]},"title":{"type":"string"},"era":{"type":"string","enum":["pre-dev","ad"]},"ratifiedByDecisionId":{"type":["string","null"]},"ratifiedAt":{"anyOf":[{"type":"string"},{"type":"string"},{"type":"null"}]},"documentCount":{"type":"integer"},"draftCount":{"type":"integer"},"ratifiedCount":{"type":"integer"},"parkedPendingCount":{"type":"integer"},"updatedAt":{"anyOf":[{"type":"string"},{"type":"string"}]}},"required":["key","kind","title","era","ratifiedByDecisionId","ratifiedAt","documentCount","draftCount","ratifiedCount","parkedPendingCount","updatedAt"]},"AdDocument":{"allOf":[{"$ref":"#/components/schemas/AdDocumentSummary"}],"properties":{"frontMatter":{"type":"object","additionalProperties":{}},"bodyMd":{"type":"string"},"clauses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"section":{"type":"string"},"text":{"type":"string"},"status":{"type":"string","const":"current"}},"required":["id","section","text","status"]}},"retiredClauses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"retiredIn":{"type":"string"}},"required":["id","retiredIn"]}},"parked":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"line":{"type":"integer"}},"required":["text","line"]}},"parkedAcknowledgement":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["pending","acknowledged"]},"itemsSha256":{"type":"string"},"acknowledgedAt":{"anyOf":[{"type":"string"},{"type":"string"},{"type":"null"}]},"acknowledgedByLabel":{"type":["string","null"]}},"required":["status","itemsSha256","acknowledgedAt","acknowledgedByLabel"]},"versions":{"type":"array","items":{"$ref":"#/components/schemas/AdDocumentVersionSummary"}}},"required":["frontMatter","bodyMd","clauses","retiredClauses","parked","parkedAcknowledgement","versions"]},"AdDocumentVersionSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"version":{"type":"string"},"basedOnVersion":{"type":["string","null"]},"changeClass":{"type":"string","enum":["ruling","conformance","editorial"]},"changeNote":{"type":"string"},"decisionId":{"type":["string","null"]},"meaningUnchangedReason":{"type":["string","null"]},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer"},"createdByLabel":{"type":"string"},"createdAt":{"anyOf":[{"type":"string"},{"type":"string"}]}},"required":["id","version","basedOnVersion","changeClass","changeNote","decisionId","meaningUnchangedReason","bodySha256","bodyBytes","createdByLabel","createdAt"]},"AdDocumentVersion":{"allOf":[{"$ref":"#/components/schemas/AdDocumentVersionSummary"}],"properties":{"bodyMd":{"type":"string"},"frontMatter":{"type":"object","additionalProperties":{}},"incorporates":{"type":"array","items":{"type":"string"}},"groundedAt":{"type":["string","null"]},"clauses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"section":{"type":"string"},"text":{"type":"string"}},"required":["id","section","text"]}},"parked":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"line":{"type":"integer"}},"required":["text","line"]}}},"required":["bodyMd","frontMatter","incorporates","groundedAt","clauses","parked"]},"AdDocumentDiff":{"type":"object","properties":{"code":{"type":"string"},"from":{"type":["string","null"]},"to":{"type":"string"},"unified":{"type":"string"},"clauses":{"type":"object","properties":{"added":{"type":"array","items":{"type":"string"}},"removed":{"type":"array","items":{"type":"string"}},"changed":{"type":"array","items":{"type":"string"}}},"required":["added","removed","changed"]}},"required":["code","from","to","unified","clauses"]},"AdDecisionListItem":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer"},"title":{"type":"string"},"kind":{"type":"string","enum":["ruling","ratification"]},"lockedAt":{"anyOf":[{"type":"string"},{"type":"string"},{"type":"null"}]},"amendsCount":{"type":"integer"},"docCodes":{"type":"array","items":{"type":"string"}}},"required":["id","number","title","kind","lockedAt","amendsCount","docCodes"]},"AdDecisionDetail":{"allOf":[{"$ref":"#/components/schemas/AdDecision"}],"properties":{"diffs":{"type":"array","items":{"$ref":"#/components/schemas/AdDocumentDiff"}}},"required":["diffs"]},"AdLockAndAmend":{"type":"object","properties":{"decision":{"$ref":"#/components/schemas/AdDecisionInput"},"documents":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","maxLength":1024},"content":{"type":"string","minLength":1,"maxLength":2000000},"baseVersion":{"type":["string","null"],"pattern":"^\\d{1,4}(\\.\\d{1,4})?$"},"conformanceRef":{"type":"string","minLength":1,"maxLength":500},"meaningUnchangedReason":{"type":"string","minLength":1,"maxLength":4000}},"required":["content","baseVersion"]},"minItems":1,"maxItems":500}},"required":["decision","documents"]},"Standardization":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"rule":{"type":"string"},"implementation":{"type":"string"},"rationale":{"type":"string"},"owner":{"type":"string"},"effort":{"type":"string"},"operatorAnswersApplied":{"type":["string","null"]},"closes":{"type":"array","items":{"type":"string"}},"closesCount":{"type":"integer"},"queueQuestions":{"type":"array","items":{"type":"string"}},"verdict":{"type":"object","properties":{"ref":{"type":"string"},"verdict":{"type":"string"},"at":{"type":["string","null"]},"note":{"type":"string"}},"required":["ref","verdict","at","note"]},"status":{"type":"string","enum":["ratified","held","in_progress","done","wont_do"]},"issueKeys":{"type":"array","items":{"type":"string"}},"issues":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"serviceId":{"type":"string"}},"required":["key","title","status","serviceId"]}},"decisionId":{"type":["string","null"]},"progressNote":{"type":["string","null"]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"string"}]}},"required":["id","name","rule","implementation","rationale","owner","effort","operatorAnswersApplied","closes","closesCount","queueQuestions","verdict","status","issueKeys","issues","decisionId","progressNote","updatedAt"]},"ArchiveItem":{"type":"object","properties":{"kind":{"type":"string","enum":["decision","doctrine","feature_doc","drift","request","open_question"]},"id":{"type":"string"},"citation":{"type":["string","null"]},"title":{"type":"string"},"status":{"type":["string","null"]},"serviceId":{"type":["string","null"]},"createdAt":{"anyOf":[{"type":"string"},{"type":"string"}]},"url":{"type":"string"}},"required":["kind","id","citation","title","status","serviceId","createdAt","url"]},"Harness":{"type":"object","properties":{"repo":{"type":"string"},"serviceId":{"type":["string","null"]},"methodologyVersion":{"type":"string"},"generatedAt":{"anyOf":[{"type":"string"},{"type":"string"}]},"sources":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"version":{"type":"string"},"status":{"type":"string","enum":["draft","ratified"]}},"required":["code","title","version","status"]}},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"kind":{"type":"string","enum":["pointer","skill","settings","stamp"]},"mode":{"type":"string","enum":["managed-block","replace","merge-json"]},"content":{"type":"string"},"sha256":{"type":"string"}},"required":["path","kind","mode","content","sha256"]}},"warnings":{"type":"array","items":{"type":"string"}}},"required":["repo","serviceId","methodologyVersion","generatedAt","sources","files","warnings"]},"Project":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"projectKey":{"type":"string"},"title":{"type":"string"},"summary":{"type":["string","null"]},"status":{"type":"string","enum":["draft","scope_confirmed","implementing","verifying","complete","abandoned"]},"planS3Key":{"type":["string","null"]},"planSha256":{"type":["string","null"]},"planBytes":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"claimedByAgentId":{"type":["string","null"],"format":"uuid"},"claimExpiresAt":{"type":["string","null"]},"scopeConfirmedAt":{"type":["string","null"]},"scopeConfirmedByAgentId":{"type":["string","null"],"format":"uuid"},"completedAt":{"type":["string","null"]},"completedByAgentId":{"type":["string","null"],"format":"uuid"},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","projectKey","title","summary","status","planS3Key","planSha256","planBytes","claimedByAgentId","claimExpiresAt","scopeConfirmedAt","scopeConfirmedByAgentId","completedAt","completedByAgentId","createdByAgentId","createdAt","updatedAt"]},"ProjectDoctrineCoverage":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"projectId":{"type":"string","format":"uuid"},"doctrineKey":{"type":"string"},"applicability":{"type":"string","enum":["applicable","not-applicable"]},"note":{"type":"string"},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","projectId","doctrineKey","applicability","note","createdByAgentId","createdAt","updatedAt"]},"Slice":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"sliceKey":{"type":"string"},"title":{"type":"string"},"splitConcurrency":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"dagOrder":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["planned","locked","implementing","partially_implemented","implemented","deprecated"]},"lockSemantics":{"type":"string"},"lockedAt":{"type":["string","null"]},"lockedByAgentId":{"type":["string","null"],"format":"uuid"},"claimedByAgentId":{"type":["string","null"],"format":"uuid"},"claimExpiresAt":{"type":["string","null"]},"completionPct":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"descriptionS3Key":{"type":["string","null"]},"descriptionSha256":{"type":["string","null"]},"descriptionBytes":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","sliceKey","title","splitConcurrency","dagOrder","status","lockSemantics","lockedAt","lockedByAgentId","claimedByAgentId","claimExpiresAt","completionPct","descriptionS3Key","descriptionSha256","descriptionBytes","createdByAgentId","createdAt","updatedAt"]},"SliceFeatureDoc":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sliceId":{"type":"string","format":"uuid"},"featureDocId":{"type":"string","format":"uuid"},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"}},"required":["id","sliceId","featureDocId","createdByAgentId","createdAt"]},"SliceFeatureDocEnriched":{"allOf":[{"$ref":"#/components/schemas/SliceFeatureDoc"}],"properties":{"docKey":{"type":["string","null"]},"version":{"type":["integer","null"]},"docStatus":{"type":["string","null"]},"supersedesId":{"type":["string","null"]}},"required":["docKey","version","docStatus","supersedesId"]},"SliceMinimum":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sliceId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["module_fn","module_type","internal_table_cols","constant","rest_surface","event_schema","cli_invocation"]},"name":{"type":"string"},"signatureMd":{"type":["string","null"]},"shapeS3Key":{"type":["string","null"]},"shapeSha256":{"type":["string","null"]},"shapeBytes":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["planned","locked","implemented","deprecated"]},"lockSemantics":{"type":"string"},"lockedAt":{"type":["string","null"]},"lockedByAgentId":{"type":["string","null"],"format":"uuid"},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","sliceId","kind","name","signatureMd","shapeS3Key","shapeSha256","shapeBytes","status","lockSemantics","lockedAt","lockedByAgentId","createdByAgentId","createdAt","updatedAt"]},"SliceBoundaryContract":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"producerSliceId":{"type":"string","format":"uuid"},"consumerSliceId":{"type":["string","null"],"format":"uuid"},"consumerServiceId":{"type":["string","null"]},"refKind":{"type":"string","enum":["artifact","minimum"]},"artifactType":{"type":["string","null"]},"artifactId":{"type":["string","null"],"format":"uuid"},"minimumId":{"type":["string","null"],"format":"uuid"},"status":{"type":"string","enum":["declared","locked","satisfied"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"}},"required":["id","producerSliceId","consumerSliceId","consumerServiceId","refKind","artifactType","artifactId","minimumId","status","createdByAgentId","createdAt"]},"SliceDep":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sliceId":{"type":"string","format":"uuid"},"dependsOnSliceId":{"type":"string","format":"uuid"},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"}},"required":["id","sliceId","dependsOnSliceId","createdByAgentId","createdAt"]},"DbTable":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"name":{"type":"string"},"schemaS3Key":{"type":"string"},"schemaSha256":{"type":"string"},"schemaBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"preseeded":{"type":"boolean"},"description":{"type":["string","null"]},"declaredIn":{"type":["string","null"]},"addedByAgentId":{"type":["string","null"],"format":"uuid"},"status":{"type":"string","enum":["planned","implementing","implemented","deprecated"]},"lockedAt":{"type":["string","null"]},"lockedByAgentId":{"type":["string","null"],"format":"uuid"},"lockedBySliceId":{"type":["string","null"],"format":"uuid"},"reconciliationState":{"type":"string","enum":["clean","dirty"]},"reconciledAt":{"type":["string","null"]},"reconciledByAgentId":{"type":["string","null"],"format":"uuid"},"dirtyReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","name","schemaS3Key","schemaSha256","schemaBytes","preseeded","description","declaredIn","addedByAgentId","status","lockedAt","lockedByAgentId","lockedBySliceId","reconciliationState","reconciledAt","reconciledByAgentId","dirtyReason","createdAt","updatedAt"]},"SqlLookup":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"name":{"type":"string"},"signatureMd":{"type":["string","null"]},"bodyS3Key":{"type":["string","null"]},"bodySha256":{"type":["string","null"]},"bodyBytes":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["planned","implementing","implemented","deprecated"]},"lockSemantics":{"type":"string"},"lockedAt":{"type":["string","null"]},"lockedByAgentId":{"type":["string","null"],"format":"uuid"},"lockedBySliceId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","name","signatureMd","bodyS3Key","bodySha256","bodyBytes","status","lockSemantics","lockedAt","lockedByAgentId","lockedBySliceId","createdAt","updatedAt"]},"RestInterface":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]},"path":{"type":"string"},"requestSchema":{},"responseSchema":{},"agentInvocable":{"type":"boolean"},"operationId":{"type":["string","null"]},"behaviorS3Key":{"type":["string","null"]},"behaviorSha256":{"type":["string","null"]},"behaviorBytes":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["planned","implemented","deprecated"]},"tier":{"type":"string","enum":["tenant-domain","platform-ops"]},"kind":{"type":"string","enum":["standard","alias"]},"aliasTargetId":{"type":["string","null"],"format":"uuid"},"lockedAt":{"type":["string","null"]},"lockedByAgentId":{"type":["string","null"],"format":"uuid"},"lockedBySliceId":{"type":["string","null"],"format":"uuid"},"reconciliationState":{"type":"string","enum":["clean","dirty"]},"reconciledAt":{"type":["string","null"]},"reconciledByAgentId":{"type":["string","null"],"format":"uuid"},"dirtyReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","method","path","agentInvocable","operationId","behaviorS3Key","behaviorSha256","behaviorBytes","status","tier","kind","aliasTargetId","lockedAt","lockedByAgentId","lockedBySliceId","reconciliationState","reconciledAt","reconciledByAgentId","dirtyReason","createdAt","updatedAt"]},"RestInterfaceWithAliasTarget":{"allOf":[{"$ref":"#/components/schemas/RestInterface"}],"properties":{"aliasTarget":{"oneOf":[{"$ref":"#/components/schemas/RestInterfaceAliasTarget"},{"type":"null"}]}},"required":["aliasTarget"]},"RestInterfaceAliasTarget":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]},"path":{"type":"string"},"status":{"type":"string","enum":["planned","implemented","deprecated"]},"tier":{"type":"string","enum":["tenant-domain","platform-ops"]},"operationId":{"type":["string","null"]}},"required":["id","serviceId","method","path","status","tier","operationId"]},"RestInterfaceWithBehavior":{"allOf":[{"$ref":"#/components/schemas/RestInterface"}],"properties":{"behaviorMd":{"type":["string","null"]}},"required":["behaviorMd"]},"GrpcInterface":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"grpcServiceName":{"type":"string"},"rpcName":{"type":"string"},"requestProto":{"type":"string"},"responseProto":{"type":"string"},"agentInvocable":{"type":"boolean"},"sagaCallable":{"type":"boolean"},"operationId":{"type":["string","null"]},"requiredParams":{},"behaviorS3Key":{"type":["string","null"]},"behaviorSha256":{"type":["string","null"]},"behaviorBytes":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["planned","implemented","deprecated"]},"lockedAt":{"type":["string","null"]},"lockedByAgentId":{"type":["string","null"],"format":"uuid"},"lockedBySliceId":{"type":["string","null"],"format":"uuid"},"reconciliationState":{"type":"string","enum":["clean","dirty"]},"reconciledAt":{"type":["string","null"]},"reconciledByAgentId":{"type":["string","null"],"format":"uuid"},"dirtyReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","grpcServiceName","rpcName","requestProto","responseProto","agentInvocable","sagaCallable","operationId","behaviorS3Key","behaviorSha256","behaviorBytes","status","lockedAt","lockedByAgentId","lockedBySliceId","reconciliationState","reconciledAt","reconciledByAgentId","dirtyReason","createdAt","updatedAt"]},"OutboxTopic":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"topicName":{"type":"string"},"payloadSchema":{},"replicationStrategy":{"type":"string","enum":["bullmq","rpc","redis-streams"]},"description":{"type":["string","null"]},"producerLocked":{"type":"boolean"},"lockedAt":{"type":["string","null"]},"lockedByAgentId":{"type":["string","null"],"format":"uuid"},"lockedBySliceId":{"type":["string","null"],"format":"uuid"},"reconciliationState":{"type":"string","enum":["clean","dirty"]},"reconciledAt":{"type":["string","null"]},"reconciledByAgentId":{"type":["string","null"],"format":"uuid"},"dirtyReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","topicName","replicationStrategy","description","producerLocked","lockedAt","lockedByAgentId","lockedBySliceId","reconciliationState","reconciledAt","reconciledByAgentId","dirtyReason","createdAt","updatedAt"]},"OutboxConsumer":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"topicId":{"type":"string","format":"uuid"},"consumerServiceId":{"type":"string"},"handlerDescription":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","topicId","consumerServiceId","handlerDescription","createdAt"]},"ApprovalKind":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"key":{"type":"string"},"label":{"type":"string"},"domain":{"type":"string"},"defaultRoute":{"$ref":"#/components/schemas/ApprovalKindDefaultRoute"},"maxLevels":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"previewSchema":{"oneOf":[{"$ref":"#/components/schemas/ApprovalKindPreviewSchema"},{"type":"null"}]},"deferredAction":{"type":["string","null"]},"outcomes":{"type":"array","items":{"type":"string","enum":["approved","rejected","expired","changes_requested","approved_with_cuts"]}},"venue":{"type":"string","enum":["home","owning_module","either"]},"slaDefault":{"oneOf":[{"$ref":"#/components/schemas/ApprovalKindSla"},{"type":"null"}]},"onTimeoutDefault":{"type":["string","null"],"enum":["escalate_next","keep_open_remind_daily","lapse","none",null]},"permissionKey":{"type":"string"},"entitlementKey":{"type":["string","null"]},"description":{"type":["string","null"]},"status":{"type":"string","enum":["planned","implementing","implemented","deprecated"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"lockedAt":{"type":["string","null"]},"lockedByAgentId":{"type":["string","null"],"format":"uuid"},"lockedBySliceId":{"type":["string","null"],"format":"uuid"},"reconciliationState":{"type":"string","enum":["clean","dirty"]},"reconciledAt":{"type":["string","null"]},"reconciledByAgentId":{"type":["string","null"],"format":"uuid"},"dirtyReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","key","label","domain","defaultRoute","maxLevels","previewSchema","deferredAction","outcomes","venue","slaDefault","onTimeoutDefault","permissionKey","entitlementKey","description","status","createdByAgentId","lockedAt","lockedByAgentId","lockedBySliceId","reconciliationState","reconciledAt","reconciledByAgentId","dirtyReason","createdAt","updatedAt"]},"ApprovalKindDefaultRoute":{"type":"object","properties":{"kind":{"type":"string","const":"org_node_walk"},"levels":{"type":"integer","minimum":1}},"required":["kind"],"additionalProperties":false},"ApprovalKindPreviewSchema":{"type":"object","properties":{"preview_label":{"type":"string","enum":["required","optional","forbidden"]},"preview_subline":{"type":"string","enum":["required","optional","forbidden"]},"counts":{"anyOf":[{"type":"string","enum":["required","optional","forbidden"]},{"type":"object","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"},"additionalProperties":{"type":"string","enum":["required","optional","forbidden"]}}]}},"additionalProperties":false},"ApprovalKindSla":{"type":"object","properties":{"value":{"type":"integer","exclusiveMinimum":0},"unit":{"type":"string","enum":["hour","business_day","working_day"]}},"required":["value","unit"],"additionalProperties":false},"Library":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"repoUrl":{"type":["string","null"]},"version":{"type":"string"},"status":{"type":"string","enum":["planned","active","deprecated"]},"description":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","repoUrl","version","status","description","createdAt","updatedAt"]},"ServiceLibraryDep":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"libraryId":{"type":"string","format":"uuid"},"versionConstraint":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","serviceId","libraryId","versionConstraint","createdAt"]},"LibraryVersion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"libraryId":{"type":"string","format":"uuid"},"version":{"type":"string"},"capabilities":{"type":["string","null"]},"commitSha":{"type":["string","null"]},"publishedAt":{"type":["string","null"]},"releaseNotes":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","libraryId","version","capabilities","commitSha","publishedAt","releaseNotes","createdAt"]},"ServiceEdge":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fromService":{"type":"string"},"toService":{"type":"string"},"kind":{"type":"string","enum":["grpc","rest","outbox","saga"]},"contractRefType":{"type":["string","null"]},"contractRefId":{"type":["string","null"],"format":"uuid"},"status":{"type":"string","enum":["planned","implemented","deprecated"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","fromService","toService","kind","contractRefType","contractRefId","status","createdAt","updatedAt"]},"ChangelogEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"agentId":{"type":["string","null"],"format":"uuid"},"commitSha":{"type":"string"},"summary":{"type":"string"},"bodyMd":{"type":["string","null"]},"prUrl":{"type":["string","null"]},"requestHash":{"type":["string","null"]},"affectedArtifacts":{},"committedAt":{"type":"string"}},"required":["id","serviceId","agentId","commitSha","summary","bodyMd","prUrl","requestHash","committedAt"]},"HealthVerdict":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"verdict":{"type":"string","enum":["good","degraded","bad"]},"reasons":{},"evaluator":{"type":"string"},"evaluatedAt":{"type":"string"}},"required":["id","serviceId","verdict","evaluator","evaluatedAt"]},"DriftEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"severity":{"type":"string","enum":["local","consumer-visible","breaking"]},"summary":{"type":"string"},"bodyMd":{"type":"string"},"status":{"type":"string","enum":["open","accepted-as-canonical","operator-resolved","superseded"]},"relatedDecisionId":{"type":["string","null"]},"relatedArtifactType":{"type":["string","null"]},"relatedArtifactId":{"type":["string","null"]},"projectId":{"type":["string","null"],"format":"uuid"},"discoveredByAgentId":{"type":["string","null"],"format":"uuid"},"resolvedBy":{"type":["string","null"]},"resolutionMd":{"type":["string","null"]},"era":{"type":"string","enum":["pre-dev","ad"]},"discoveredAt":{"type":"string"},"resolvedAt":{"type":["string","null"]}},"required":["id","serviceId","severity","summary","bodyMd","status","relatedDecisionId","relatedArtifactType","relatedArtifactId","projectId","discoveredByAgentId","resolvedBy","resolutionMd","era","discoveredAt","resolvedAt"]},"Pipeline":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["rpc_mutator","rpc_query","http_webhook","worker_cron","worker_lease"]},"trigger":{"type":"string"},"grpcInterfaceId":{"type":["string","null"],"format":"uuid"},"restInterfaceId":{"type":["string","null"],"format":"uuid"},"sagaId":{"type":["string","null"],"format":"uuid"},"sagaStepOrder":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"bodyS3Key":{"type":"string"},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["planned","implemented","deprecated"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","name","kind","trigger","grpcInterfaceId","restInterfaceId","sagaId","sagaStepOrder","bodyS3Key","bodySha256","bodyBytes","status","createdByAgentId","createdAt","updatedAt"]},"DoctrineException":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"doctrinePath":{"type":"string"},"filedAgainstDoctrineRevision":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"scope":{"type":"string"},"rationaleS3Key":{"type":"string"},"rationaleSha256":{"type":"string"},"rationaleBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"decisionId":{"type":["string","null"]},"status":{"type":"string","enum":["active","sunset_planned","revoked"]},"sunsetTargetDate":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","doctrinePath","filedAgainstDoctrineRevision","scope","rationaleS3Key","rationaleSha256","rationaleBytes","decisionId","status","sunsetTargetDate","createdByAgentId","createdAt","updatedAt"]},"Runbook":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["local_dev","operations","incident","key_management","compliance","release"]},"repoRelativePath":{"type":"string"},"summaryS3Key":{"type":"string"},"summarySha256":{"type":"string"},"summaryBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["active","stale","superseded"]},"lastVerifiedAt":{"type":["string","null"]},"supersededById":{"type":["string","null"],"format":"uuid"},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","title","kind","repoRelativePath","summaryS3Key","summarySha256","summaryBytes","status","lastVerifiedAt","supersededById","createdByAgentId","createdAt","updatedAt"]},"OpenQuestion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":["string","null"]},"module":{"type":["string","null"]},"questionMd":{"type":"string"},"contextS3Key":{"type":["string","null"]},"contextSha256":{"type":["string","null"]},"contextBytes":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["open","in_discussion","answered","obsolete"]},"answeredByDecisionId":{"type":["string","null"]},"answeredByAnswerId":{"type":["string","null"],"format":"uuid"},"raisedByAgentId":{"type":["string","null"],"format":"uuid"},"topicTags":{"type":"array","items":{"type":"string"}},"priority":{"type":"string","enum":["low","medium","high","blocker"]},"era":{"type":"string","enum":["pre-dev","ad"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","module","questionMd","contextS3Key","contextSha256","contextBytes","status","answeredByDecisionId","answeredByAnswerId","raisedByAgentId","topicTags","priority","era","createdAt","updatedAt"]},"Runner":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["agent-runner","orchestrator"]},"serviceId":{"type":["string","null"]},"baseUrl":{"type":"string"},"version":{"type":["string","null"]},"status":{"type":"string","enum":["online","degraded","offline"]},"lastHeartbeatAt":{"type":"string"},"registeredByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","kind","serviceId","baseUrl","version","status","lastHeartbeatAt","registeredByAgentId","createdAt","updatedAt"]},"RunnerRegister":{"type":"object","properties":{"kind":{"type":"string","enum":["agent-runner","orchestrator"]},"serviceId":{"type":["string","null"]},"baseUrl":{"type":"string","format":"uri","pattern":"^https?:\\/\\/"},"version":{"type":["string","null"]},"status":{"type":"string","enum":["online","degraded","offline"]}},"required":["kind","baseUrl"]},"UsageCeiling":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"runnerId":{"type":"string","format":"uuid"},"ceiling":{"type":"string","enum":["subscription","api_credit"]},"state":{"type":"string","enum":["ok","warning","exhausted"]},"resetsAt":{"type":["string","null"]},"counters":{},"observedAt":{"type":"string"}},"required":["id","runnerId","ceiling","state","resetsAt","observedAt"]},"RunnerUsageReport":{"type":"object","properties":{"ceiling":{"type":"string","enum":["subscription","api_credit"]},"state":{"type":"string","enum":["ok","warning","exhausted"]},"resetsAt":{"type":["string","null"],"format":"date-time"},"counters":{}},"required":["ceiling","state"]},"RoutingHit":{"type":"object","properties":{"serviceId":{"type":"string"},"sliceId":{"type":"string"},"runnerBaseUrl":{"type":"string"},"runnerStatus":{"type":"string","enum":["online","degraded","offline"]},"agentId":{"type":"string"}},"required":["serviceId","runnerBaseUrl","runnerStatus"]},"UsageFanInRunner":{"type":"object","properties":{"runnerId":{"type":"string","format":"uuid"},"serviceId":{"type":["string","null"]},"kind":{"type":"string","enum":["agent-runner","orchestrator"]},"baseUrl":{"type":"string"},"runnerStatus":{"type":"string","enum":["online","degraded","offline"]},"ceilings":{"type":"array","items":{"type":"object","properties":{"ceiling":{"type":"string","enum":["subscription","api_credit"]},"state":{"type":"string","enum":["ok","warning","exhausted"]},"resetsAt":{"type":["string","null"],"format":"date-time"},"observedAt":{"type":"string","format":"date-time"}},"required":["ceiling","state","resetsAt","observedAt"]}}},"required":["runnerId","serviceId","kind","baseUrl","runnerStatus","ceilings"]},"NotificationType":{"type":"object","properties":{"typeKey":{"type":"string"},"meaning":{"type":"string"},"examples":{"type":"string"},"notFor":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["typeKey","meaning","examples","notFor","createdAt","updatedAt"]},"NotificationEvent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"eventKey":{"type":"string"},"version":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"supersedesId":{"type":["string","null"],"format":"uuid"},"status":{"type":"string","enum":["proposed","approved","built","retired"]},"typeKey":{"type":"string"},"groupLabel":{"type":["string","null"]},"message":{"type":"string"},"audience":{"type":"string","enum":["customers","tenant_staff","nodii_staff","other"]},"audienceDetail":{"type":["string","null"]},"channels":{"type":"array","items":{"type":"string"}},"muteClass":{"type":["string","null"],"enum":["mutable","protected","account_email","test",null]},"billing":{"type":["string","null"],"enum":["billed","free","by_recipient",null]},"emailRoute":{"type":["string","null"],"enum":["nodii_only","prefer_tenant","prefer_tenant_guarded","none","provider_under_test",null]},"payloadSchema":{},"producerServiceIds":{"type":"array","items":{"type":"string"}},"templateKeys":{"type":["object","null"],"additionalProperties":{"type":"string"}},"builtCommitSha":{"type":["string","null"]},"replaces":{"type":"array","items":{"type":"string"}},"replacedBy":{"type":"array","items":{"type":"string"}},"decisionRefs":{"type":"array","items":{"type":"string"}},"notes":{"type":["string","null"]},"retireReason":{"type":["string","null"]},"proposedByServiceId":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","eventKey","version","supersedesId","status","typeKey","groupLabel","message","audience","audienceDetail","channels","muteClass","billing","emailRoute","producerServiceIds","templateKeys","builtCommitSha","replaces","replacedBy","decisionRefs","notes","retireReason","proposedByServiceId","createdByAgentId","createdAt","updatedAt"]},"NotificationEventPropose":{"type":"object","properties":{"eventKey":{"type":"string","minLength":1,"maxLength":200},"typeKey":{"type":"string","minLength":1,"maxLength":100},"groupLabel":{"type":["string","null"],"maxLength":2000},"message":{"type":"string","minLength":1,"maxLength":4000},"audience":{"type":"string","enum":["customers","tenant_staff","nodii_staff","other"]},"audienceDetail":{"type":["string","null"],"maxLength":2000},"channels":{"type":"array","items":{"type":"string","enum":["email","sms","whatsapp","voice","push","in_app","oob"]},"minItems":1,"maxItems":7},"muteClass":{"type":["string","null"],"enum":["mutable","protected","account_email","test",null]},"billing":{"type":["string","null"],"enum":["billed","free","by_recipient",null]},"emailRoute":{"type":["string","null"],"enum":["nodii_only","prefer_tenant","prefer_tenant_guarded","none","provider_under_test",null]},"payloadSchema":{"type":["object","null"],"additionalProperties":{}},"producerServiceIds":{"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"minItems":1,"maxItems":50},"replaces":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":100},"decisionRefs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50},"maxItems":100},"notes":{"type":["string","null"],"maxLength":8000}},"required":["eventKey","typeKey","message","audience","channels","producerServiceIds"],"additionalProperties":false},"NotificationEventRevise":{"type":"object","properties":{"typeKey":{"type":"string","minLength":1,"maxLength":100},"groupLabel":{"type":["string","null"],"maxLength":2000},"message":{"type":"string","minLength":1,"maxLength":4000},"audience":{"type":"string","enum":["customers","tenant_staff","nodii_staff","other"]},"audienceDetail":{"type":["string","null"],"maxLength":2000},"channels":{"type":"array","items":{"type":"string","enum":["email","sms","whatsapp","voice","push","in_app","oob"]},"minItems":1,"maxItems":7},"muteClass":{"type":["string","null"],"enum":["mutable","protected","account_email","test",null]},"billing":{"type":["string","null"],"enum":["billed","free","by_recipient",null]},"emailRoute":{"type":["string","null"],"enum":["nodii_only","prefer_tenant","prefer_tenant_guarded","none","provider_under_test",null]},"payloadSchema":{"type":["object","null"],"additionalProperties":{}},"producerServiceIds":{"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"minItems":1,"maxItems":50},"replaces":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":100},"decisionRefs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50},"maxItems":100},"notes":{"type":["string","null"],"maxLength":8000}},"additionalProperties":false},"NotificationEventApprove":{"type":"object","properties":{"muteClass":{"type":"string","enum":["mutable","protected","account_email","test"]},"billing":{"type":"string","enum":["billed","free","by_recipient"]},"emailRoute":{"type":"string","enum":["nodii_only","prefer_tenant","prefer_tenant_guarded","none","provider_under_test"]},"payloadSchema":{"type":["object","null"],"additionalProperties":{}},"notes":{"type":["string","null"],"maxLength":8000}},"required":["muteClass","billing","emailRoute"],"additionalProperties":false},"NotificationEventMarkBuilt":{"type":"object","properties":{"templateKeys":{"type":"object","properties":{"email":{"type":"string","minLength":1,"maxLength":200},"sms":{"type":"string","minLength":1,"maxLength":200},"whatsapp":{"type":"string","minLength":1,"maxLength":200},"voice":{"type":"string","minLength":1,"maxLength":200},"push":{"type":"string","minLength":1,"maxLength":200},"in_app":{"type":"string","minLength":1,"maxLength":200},"oob":{"type":"string","minLength":1,"maxLength":200}},"additionalProperties":false},"commitSha":{"type":"string","pattern":"^[0-9a-f]{7,40}$"}},"required":["templateKeys","commitSha"],"additionalProperties":false},"NotificationEventRetire":{"type":"object","properties":{"replacedBy":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":50},"reason":{"type":"string","maxLength":2000}},"additionalProperties":false},"Worker":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"workerKey":{"type":"string"},"kind":{"type":"string","enum":["cron","sweeper","consumer","saga-runner","outbox-drainer","queue-worker","reconciler","other"]},"description":{"type":["string","null"]},"cadence":{"type":["string","null"]},"cadenceSeconds":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"sourcePath":{"type":["string","null"]},"entrypoints":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["planned","implementing","partially_implemented","implemented","deprecated"]},"idempotent":{"type":["boolean","null"]},"tenancy":{"type":["string","null"],"enum":["per-tenant","global",null]},"concurrencyGuard":{"type":["string","null"],"enum":["none","lease","advisory-lock","consumer-group","queue","row-lock",null]},"processIsolation":{"type":"string","enum":["compliant","non_compliant","unknown"]},"isolationEvidence":{"type":["string","null"]},"deployedAs":{"type":["string","null"]},"contractRefs":{"type":"array","items":{"type":"string"}},"ackBehavior":{"type":["string","null"]},"retryBackoff":{"type":["string","null"]},"ratification":{"type":"string","enum":["unratified","ratified","disputed"]},"ratifiedAt":{"type":["string","null"]},"ratifiedByAgentId":{"type":["string","null"],"format":"uuid"},"ratificationNote":{"type":["string","null"]},"provenance":{"type":"string","enum":["hub-scan","service"]},"scannedCommitSha":{"type":["string","null"]},"decisionRefs":{"type":"array","items":{"type":"string"}},"addedByAgentId":{"type":["string","null"],"format":"uuid"},"reconciliationState":{"type":"string","enum":["clean","dirty"]},"reconciledAt":{"type":["string","null"]},"reconciledByAgentId":{"type":["string","null"],"format":"uuid"},"dirtyReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","workerKey","kind","description","cadence","cadenceSeconds","sourcePath","entrypoints","status","idempotent","tenancy","concurrencyGuard","processIsolation","isolationEvidence","deployedAs","contractRefs","ackBehavior","retryBackoff","ratification","ratifiedAt","ratifiedByAgentId","ratificationNote","provenance","scannedCommitSha","decisionRefs","addedByAgentId","reconciliationState","reconciledAt","reconciledByAgentId","dirtyReason","createdAt","updatedAt"]},"WorkerServiceSummary":{"type":"object","properties":{"serviceId":{"type":"string"},"total":{"type":"integer"},"compliant":{"type":"integer"},"non_compliant":{"type":"integer"},"unknown":{"type":"integer"},"unratified":{"type":"integer"},"ratified":{"type":"integer"},"disputed":{"type":"integer"}},"required":["serviceId","total","compliant","non_compliant","unknown","unratified","ratified","disputed"]},"WorkerCreate":{"type":"object","properties":{"workerKey":{"type":"string","minLength":1,"maxLength":200},"kind":{"type":"string","enum":["cron","sweeper","consumer","saga-runner","outbox-drainer","queue-worker","reconciler","other"]},"status":{"type":"string","enum":["planned","implementing","partially_implemented","implemented","deprecated"]},"description":{"type":["string","null"],"maxLength":4000},"cadence":{"type":["string","null"],"maxLength":200},"cadenceSeconds":{"type":["integer","null"],"exclusiveMinimum":0},"sourcePath":{"type":["string","null"],"maxLength":500},"entrypoints":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500},"maxItems":50},"idempotent":{"type":["boolean","null"]},"tenancy":{"type":["string","null"],"enum":["per-tenant","global",null]},"concurrencyGuard":{"type":["string","null"],"enum":["none","lease","advisory-lock","consumer-group","queue","row-lock",null]},"processIsolation":{"type":"string","enum":["compliant","non_compliant","unknown"]},"isolationEvidence":{"type":["string","null"],"maxLength":4000},"deployedAs":{"type":["string","null"],"maxLength":500},"contractRefs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":100},"ackBehavior":{"type":["string","null"],"maxLength":4000},"retryBackoff":{"type":["string","null"],"maxLength":4000},"decisionRefs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50},"maxItems":100}},"required":["workerKey","kind"],"additionalProperties":false},"WorkerPreseedResult":{"type":"object","properties":{"inserted":{"type":"integer"},"updated":{"type":"integer"},"skipped":{"type":"integer"},"conflicts":{"type":"array","items":{"type":"object","properties":{"workerKey":{"type":"string"},"existingServiceId":{"type":"string"}},"required":["workerKey","existingServiceId"]}}},"required":["inserted","updated","skipped","conflicts"]},"WorkerPreseed":{"type":"object","properties":{"scannedCommitSha":{"type":"string","pattern":"^[0-9a-f]{7,40}$"},"workers":{"type":"array","items":{"$ref":"#/components/schemas/WorkerCreate"},"minItems":1,"maxItems":500}},"required":["workers"],"additionalProperties":false},"WorkerPatch":{"type":"object","properties":{"kind":{"type":"string","enum":["cron","sweeper","consumer","saga-runner","outbox-drainer","queue-worker","reconciler","other"]},"description":{"type":["string","null"],"maxLength":4000},"cadence":{"type":["string","null"],"maxLength":200},"cadenceSeconds":{"type":["integer","null"],"exclusiveMinimum":0},"sourcePath":{"type":["string","null"],"maxLength":500},"entrypoints":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500},"maxItems":50},"idempotent":{"type":["boolean","null"]},"tenancy":{"type":["string","null"],"enum":["per-tenant","global",null]},"concurrencyGuard":{"type":["string","null"],"enum":["none","lease","advisory-lock","consumer-group","queue","row-lock",null]},"processIsolation":{"type":"string","enum":["compliant","non_compliant","unknown"]},"isolationEvidence":{"type":["string","null"],"maxLength":4000},"deployedAs":{"type":["string","null"],"maxLength":500},"contractRefs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":100},"ackBehavior":{"type":["string","null"],"maxLength":4000},"retryBackoff":{"type":["string","null"],"maxLength":4000},"decisionRefs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50},"maxItems":100}},"additionalProperties":false},"WorkerDispute":{"type":"object","properties":{"reason":{"type":"string","minLength":10,"maxLength":4000},"corrections":{"type":"object","additionalProperties":{}}},"required":["reason"],"additionalProperties":false},"Issue":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"serviceId":{"type":"string"},"title":{"type":"string"},"bodyS3Key":{"type":["string","null"]},"bodySha256":{"type":["string","null"]},"bodyBytes":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"kind":{"type":"string","enum":["feature","bug","chore","drift","request","verification"]},"status":{"type":"string","enum":["todo","in_progress","in_review","blocked","done","wont_do"]},"priority":{"type":"string","enum":["p0","p1","p2","p3"]},"project":{"type":["string","null"]},"source":{"type":"string","enum":["manual","backlog_import","drift","request","ticket"]},"sourceRef":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{}},"claimedByAgentId":{"type":["string","null"],"format":"uuid"},"claimedOnBehalfOf":{"type":["string","null"]},"claimExpiresAt":{"type":["string","null"]},"links":{"$ref":"#/components/schemas/IssueLinks"},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"closedAt":{"type":["string","null"]}},"required":["id","key","serviceId","title","bodyS3Key","bodySha256","bodyBytes","kind","status","priority","project","source","sourceRef","metadata","claimedByAgentId","claimedOnBehalfOf","claimExpiresAt","links","createdByAgentId","createdAt","updatedAt","closedAt"]},"IssueLinks":{"type":"object","properties":{"prs":{"type":"array","items":{"type":"string"},"default":[]},"changes":{"type":"array","items":{"type":"string"},"default":[]},"builds":{"type":"array","items":{"type":"string"},"default":[]},"decisions":{"type":"array","items":{"type":"string"},"default":[]}},"required":["prs","changes","builds","decisions"]},"IssueDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"serviceId":{"type":"string"},"title":{"type":"string"},"bodyS3Key":{"type":["string","null"]},"bodySha256":{"type":["string","null"]},"bodyBytes":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"kind":{"type":"string","enum":["feature","bug","chore","drift","request","verification"]},"status":{"type":"string","enum":["todo","in_progress","in_review","blocked","done","wont_do"]},"priority":{"type":"string","enum":["p0","p1","p2","p3"]},"project":{"type":["string","null"]},"source":{"type":"string","enum":["manual","backlog_import","drift","request","ticket"]},"sourceRef":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{}},"claimedByAgentId":{"type":["string","null"],"format":"uuid"},"claimedOnBehalfOf":{"type":["string","null"]},"claimExpiresAt":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"closedAt":{"type":["string","null"]},"links":{"type":"object","properties":{"prs":{"type":"array","items":{"type":"string"},"default":[]},"changes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":["string","null"]}},"required":["id","title"]}},"builds":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":["string","null"]}},"required":["id","title"]}},"decisions":{"type":"array","items":{"type":"string"},"default":[]}},"required":["prs","changes","builds","decisions"]},"bodyMd":{"type":["string","null"]},"events":{"type":"array","items":{"$ref":"#/components/schemas/IssueEvent"}},"transitions":{"type":"array","items":{"type":"string","enum":["todo","in_progress","in_review","blocked","done","wont_do"]}},"leaseLive":{"type":"boolean"},"laneIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["id","key","serviceId","title","bodyS3Key","bodySha256","bodyBytes","kind","status","priority","project","source","sourceRef","metadata","claimedByAgentId","claimedOnBehalfOf","claimExpiresAt","createdByAgentId","createdAt","updatedAt","closedAt","links","bodyMd","events","transitions","leaseLive","laneIds"]},"IssueEvent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"issueId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["created","updated","status_changed","claimed","claim_renewed","released","claim_expired","commented","backlog_added","backlog_moved","backlog_removed","imported"]},"actorAgentId":{"type":["string","null"],"format":"uuid"},"actorLabel":{"type":["string","null"]},"fromStatus":{"type":["string","null"],"enum":["todo","in_progress","in_review","blocked","done","wont_do",null]},"toStatus":{"type":["string","null"],"enum":["todo","in_progress","in_review","blocked","done","wont_do",null]},"note":{"type":["string","null"]},"data":{"type":"object","additionalProperties":{}},"createdAt":{"type":"string"}},"required":["id","issueId","kind","actorAgentId","actorLabel","fromStatus","toStatus","note","data","createdAt"]},"Backlog":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"serviceId":{"type":["string","null"]},"project":{"type":["string","null"]},"description":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","slug","name","serviceId","project","description","createdByAgentId","createdAt","updatedAt"]},"BacklogDetail":{"allOf":[{"$ref":"#/components/schemas/Backlog"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BacklogEntry"}}},"required":["items"]},"BacklogEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["todo","in_progress","in_review","blocked","done","wont_do"]},"priority":{"type":"string","enum":["p0","p1","p2","p3"]},"kind":{"type":"string","enum":["feature","bug","chore","drift","request","verification"]},"serviceId":{"type":"string"},"project":{"type":["string","null"]},"claimedByAgentId":{"type":["string","null"]},"claimedOnBehalfOf":{"type":["string","null"]},"claimExpiresAt":{"type":["string","null"]},"position":{"type":"number"},"addedAt":{"type":"string"}},"required":["id","key","title","status","priority","kind","serviceId","project","claimedByAgentId","claimedOnBehalfOf","claimExpiresAt","position","addedAt"]},"ServiceWorkSummary":{"type":"object","properties":{"serviceId":{"type":"string"},"openTotal":{"type":"integer"},"openByStatus":{"type":"object","properties":{"todo":{"type":"integer"},"in_progress":{"type":"integer"},"in_review":{"type":"integer"},"blocked":{"type":"integer"}},"required":["todo","in_progress","in_review","blocked"]},"claimedNow":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["todo","in_progress","in_review","blocked","done","wont_do"]},"claimedByAgentId":{"type":["string","null"]},"claimedOnBehalfOf":{"type":["string","null"]},"claimExpiresAt":{"type":["string","null"]}},"required":["id","key","title","status","claimedByAgentId","claimedOnBehalfOf","claimExpiresAt"]}},"oldestOpen":{"type":["object","null"],"properties":{"id":{"type":"string"},"key":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["todo","in_progress","in_review","blocked","done","wont_do"]},"createdAt":{"type":"string"}},"required":["id","key","title","status","createdAt"]}},"required":["serviceId","openTotal","openByStatus","claimedNow","oldestOpen"]},"Build":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"repo":{"type":"string"},"environment":{"type":"string","enum":["dev","uat","prod"]},"workflowPath":{"type":["string","null"]},"commitSha":{"type":"string"},"imageDigest":{"type":["string","null"]},"prNumber":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"ciStatus":{"type":"string","enum":["unknown","pending","success","bypassed","failure","cancelled"]},"deployStatus":{"type":"string","enum":["queued","in_progress","success","failure","cancelled"]},"runId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"runUrl":{"type":"string"},"startedAt":{"type":"string"},"completedAt":{"type":["string","null"]},"source":{"type":"string","enum":["github_actions_poll","deploy_report"]},"changesBaseSha":{"type":["string","null"]},"changesComputedAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","repo","environment","workflowPath","commitSha","imageDigest","prNumber","ciStatus","deployStatus","runId","runUrl","startedAt","completedAt","source","changesBaseSha","changesComputedAt","createdAt","updatedAt"]},"BuildView":{"allOf":[{"$ref":"#/components/schemas/Build"}],"properties":{"blocked":{"type":"boolean"}},"required":["blocked"]},"BuildSummary":{"type":"object","properties":{"serviceId":{"type":"string"},"environment":{"type":"string","enum":["dev","uat","prod"]},"latestBuild":{"$ref":"#/components/schemas/Build"},"countsByCiStatus":{"type":"object","properties":{"unknown":{"type":"integer"},"pending":{"type":"integer"},"success":{"type":"integer"},"bypassed":{"type":"integer"},"failure":{"type":"integer"},"cancelled":{"type":"integer"}},"required":["unknown","pending","success","bypassed","failure","cancelled"]},"countsByDeployStatus":{"type":"object","properties":{"queued":{"type":"integer"},"in_progress":{"type":"integer"},"success":{"type":"integer"},"failure":{"type":"integer"},"cancelled":{"type":"integer"}},"required":["queued","in_progress","success","failure","cancelled"]}},"required":["serviceId","environment","latestBuild","countsByCiStatus","countsByDeployStatus"]},"BuildDetail":{"allOf":[{"$ref":"#/components/schemas/BuildView"}],"properties":{"blockingChangeIds":{"type":"array","items":{"type":"string","format":"uuid"}},"changes":{"type":"array","items":{"$ref":"#/components/schemas/Change"}}},"required":["blockingChangeIds","changes"]},"Change":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":"string"},"repo":{"type":"string"},"prNumber":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"title":{"type":"string"},"prUrl":{"type":"string"},"baseBranch":{"type":"string"},"mergedAt":{"type":"string"},"mergedBy":{"type":["string","null"]},"mergeCommitSha":{"type":"string"},"changelogEntryId":{"type":["string","null"],"format":"uuid"},"mark":{"type":"string","enum":["unverified","verified","broken","rolled_back"]},"markReason":{"type":["string","null"]},"markedByAgentId":{"type":["string","null"],"format":"uuid"},"markedAt":{"type":["string","null"]},"fixedByChangeId":{"type":["string","null"],"format":"uuid"},"touches":{"type":"array","items":{"type":"string"}},"userVisible":{"type":"boolean"},"userVisibleOverridden":{"type":"boolean"},"filesFetchedAt":{"type":["string","null"]},"filesTruncated":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","serviceId","repo","prNumber","title","prUrl","baseBranch","mergedAt","mergedBy","mergeCommitSha","changelogEntryId","mark","markReason","markedByAgentId","markedAt","fixedByChangeId","touches","userVisible","userVisibleOverridden","filesFetchedAt","filesTruncated","createdAt","updatedAt"]},"BuildReport":{"type":"object","properties":{"serviceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"environment":{"type":"string","enum":["dev","uat","prod"]},"commitSha":{"type":"string","pattern":"^[0-9a-f]{40}$"},"runUrl":{"type":"string","pattern":"^https:\\/\\/github\\.com\\/([A-Za-z0-9_.-]+\\/[A-Za-z0-9_.-]+)\\/actions\\/runs\\/(\\d+)(?:\\/.*)?$"},"repo":{"type":"string","pattern":"^[A-Za-z0-9_.-]+\\/[A-Za-z0-9_.-]+$"},"runId":{"type":"integer","exclusiveMinimum":0},"imageDigest":{"type":["string","null"],"pattern":"^sha256:[0-9a-f]{64}$"},"prNumber":{"type":["integer","null"],"exclusiveMinimum":0},"conclusion":{"type":"string","enum":["queued","in_progress","success","failure","cancelled"]},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}},"required":["serviceId","environment","commitSha","runUrl","conclusion"]},"ChangeView":{"allOf":[{"$ref":"#/components/schemas/Change"}],"properties":{"changelogSummary":{"type":["string","null"]}},"required":["changelogSummary"]},"ChangeDetail":{"allOf":[{"$ref":"#/components/schemas/ChangeView"}],"properties":{"builds":{"type":"array","items":{"$ref":"#/components/schemas/Build"}},"files":{"type":"array","items":{"$ref":"#/components/schemas/ChangeFile"}}},"required":["builds","files"]},"ChangeFile":{"type":"object","properties":{"path":{"type":"string"},"status":{"type":"string"},"additions":{"type":"integer"},"deletions":{"type":"integer"},"previousPath":{"type":["string","null"]}},"required":["path","status","additions","deletions","previousPath"]},"ChangeMarkInput":{"type":"object","properties":{"mark":{"type":"string","enum":["unverified","verified","broken","rolled_back"]},"reason":{"type":["string","null"],"maxLength":4000},"fixedByChangeId":{"type":["string","null"],"format":"uuid"},"userVisible":{"type":"boolean"}}},"ServiceDelivery":{"type":"object","properties":{"serviceId":{"type":"string"},"lastBuilds":{"type":"array","items":{"$ref":"#/components/schemas/BuildView"}},"changes":{"type":"object","properties":{"unverified":{"type":"integer"},"verified":{"type":"integer"},"broken":{"type":"integer"},"rolled_back":{"type":"integer"}},"required":["unverified","verified","broken","rolled_back"]}},"required":["serviceId","lastBuilds","changes"]},"DeliveryPollState":{"type":"object","properties":{"repo":{"type":"string"},"serviceId":{"type":"string"},"defaultBranch":{"type":["string","null"]},"prHwm":{"type":["string","null"]},"runHwm":{"type":["string","null"]},"deployWorkflows":{},"ciWorkflows":{},"workflowsDiscoveredAt":{"type":["string","null"]},"lastPolledAt":{"type":["string","null"]},"lastSuccessAt":{"type":["string","null"]},"lastError":{"type":["string","null"]},"consecutiveFailures":{"type":"integer"},"updatedAt":{"type":"string"}},"required":["repo","serviceId","defaultBranch","prHwm","runHwm","workflowsDiscoveredAt","lastPolledAt","lastSuccessAt","lastError","consecutiveFailures","updatedAt"]},"DeployObservation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceId":{"type":["string","null"]},"serviceRepo":{"type":"string"},"environment":{"type":"string","enum":["dev","uat","prod"]},"cluster":{"type":"string"},"deployable":{"type":"string"},"taskDefinitionArn":{"type":"string"},"image":{"type":"string"},"imageDigest":{"type":"string"},"commitSha":{"type":"string"},"desiredCount":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"runningCount":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"rolloutState":{"type":"string","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"deployedAt":{"type":"string"},"observedAt":{"type":"string"},"workflowRunUrl":{"type":"string"},"actor":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","serviceId","serviceRepo","environment","cluster","deployable","taskDefinitionArn","image","imageDigest","commitSha","desiredCount","runningCount","rolloutState","deployedAt","observedAt","workflowRunUrl","actor","createdAt"]},"DeployReportInput":{"type":"object","properties":{"service_repo":{"type":"string","pattern":"^cognion-nucleus\\/[A-Za-z0-9._-]+$"},"env":{"type":"string","const":"dev"},"cluster":{"type":"string","minLength":1},"deployable":{"type":"string","minLength":1},"task_definition_arn":{"type":"string","minLength":1},"image":{"type":"string","minLength":1},"image_digest":{"type":"string","pattern":"^sha256:[a-fA-F0-9]{64}$"},"commit_sha":{"type":"string","pattern":"^[a-fA-F0-9]{40}$"},"desired_count":{"type":"integer","minimum":0},"running_count":{"type":"integer","minimum":0},"rollout_state":{"type":"string","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"deployed_at":{"type":"string","format":"date-time"},"observed_at":{"type":"string","format":"date-time"},"workflow_run_url":{"type":"string","format":"uri"},"actor":{"type":"string","minLength":1}},"required":["service_repo","env","cluster","deployable","task_definition_arn","image","image_digest","commit_sha","desired_count","running_count","rollout_state","deployed_at","observed_at","workflow_run_url","actor"],"additionalProperties":false},"RuntimeObservation":{"allOf":[{"$ref":"#/components/schemas/DeployObservation"}],"properties":{"stalenessSeconds":{"type":"integer","minimum":0},"build":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"runUrl":{"type":"string","format":"uri"},"deployStatus":{"type":"string"}},"required":["id","runUrl","deployStatus"]}},"required":["stalenessSeconds","build"]},"Machine":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"hostFacts":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"coordinatorAgentId":{"type":"string","format":"uuid"},"heavySlotTotal":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"memoryFacts":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"lastReportAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","hostFacts","coordinatorAgentId","heavySlotTotal","memoryFacts","lastReportAt","createdAt","updatedAt"]},"FleetGateResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"gatedServiceCount":{"type":"integer","minimum":0},"totals":{"type":"object","properties":{"drift":{"type":"integer","minimum":0},"request":{"type":"integer","minimum":0},"question":{"type":"integer","minimum":0},"all":{"type":"integer","minimum":0}},"required":["drift","request","question","all"]},"services":{"type":"array","items":{"type":"object","properties":{"serviceId":{"type":"string"},"total":{"type":"integer","minimum":0},"byKind":{"type":"object","properties":{"drift":{"type":"integer","minimum":0},"request":{"type":"integer","minimum":0},"question":{"type":"integer","minimum":0}},"required":["drift","request","question"]},"oldest":{"type":"object","properties":{"kind":{"type":"string","enum":["drift","request","question","lane_escalation","credential_expiry"]},"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"ageSeconds":{"type":"integer","minimum":0}},"required":["kind","id","title","createdAt","ageSeconds"]}},"required":["serviceId","total","byKind","oldest"]}},"computedAt":{"type":"string","format":"date-time"}},"required":["gatedServiceCount","totals","services","computedAt"]}},"required":["data"]}}},"paths":{"/api/v1/health":{"get":{"responses":{"200":{"description":"Service is alive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}},"operationId":"getHealth","tags":["Health"],"parameters":[],"summary":"Health probe","description":"Open endpoint. Returns 200 if the process is alive, with the state of the devops permission catalog publish. No DB probe — use /health/db for that."}},"/api/v1/services":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Service"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServices","tags":["Services"],"parameters":[],"summary":"List all services","description":"Returns every service in the platform, ordered by migration wave then id."},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Service"}},"required":["data"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createService","tags":["Services"],"parameters":[],"summary":"Register a new service","description":"Idempotent — calling with an existing id returns the existing row (use PATCH for explicit updates).","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceInsert"}}}}}},"/api/v1/services/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Service"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getService","tags":["Services"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Get a service by id"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Service"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateService","tags":["Services"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Update a service","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"name":{"type":"string"},"wave":{"type":"integer","minimum":0,"maximum":5},"status":{"type":"string","enum":["planned","feature_docs_drafting","contracts_authoring","scaffolding","implementing","partially_implemented","implemented","live","active","deprecated","frozen"]},"owner":{"type":["string","null"]},"repoUrl":{"type":["string","null"]},"description":{"type":["string","null"]},"activeImplementerAgentId":{"type":["string","null"],"format":"uuid"},"lastImplSessionAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}}}}}}}},"/api/v1/services/{id}/mark-implementing":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Service"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"markServiceImplementing","tags":["Services"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Mark a service as actively being implemented by an agent","description":"Sets active_implementer_agent_id + bumps last_impl_session_at. Promotes status forward to 'implementing' if currently in a pre-impl phase. Idempotent — same agent calling repeatedly only bumps the timestamp.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"}},"required":["agentId"]}}}}}},"/api/v1/services/{id}/clear-implementer":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Service"}},"required":["data"]}}}},"404":{"description":"Not found or expectedAgentId mismatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"clearServiceImplementer","tags":["Services"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Clear the active implementer pointer for a service","description":"If expectedAgentId is provided, only clears when the current pointer matches (used by the pruner to avoid clobbering a fresh session). Returns 404 if the service doesn't exist OR if expectedAgentId didn't match.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"expectedAgentId":{"type":"string","format":"uuid"}}}}}}}},"/api/v1/services/{id}/recompute-status":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Service"},"facts":{"$ref":"#/components/schemas/ServiceStatusFacts"}},"required":["data","facts"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"recomputeServiceStatus","tags":["Services"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Recompute a service's status from authoritative Dev state","description":"Promotion ladder: planned → feature_docs_drafting → contracts_authoring → implementing → partially_implemented → implemented. Skips terminal states (live, deprecated, frozen) and legacy states (active, scaffolding) — operator-only territory."}},"/api/v1/agents":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Agent"}],"properties":{"personDisplayName":{"type":"object","properties":{"value":{"type":["string","null"]},"masked":{"type":"boolean"},"hint":{"type":["string","null"]}},"required":["value","masked","hint"]}},"required":["personDisplayName"]}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listAgents","tags":["Agents"],"parameters":[],"summary":"List all agents","description":"Ordered by last_seen_at desc; includes heartbeatIntervalSeconds and authenticationMethod."},"post":{"responses":{"201":{"description":"Registered (created or refreshed)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Agent"}},"required":["data"]}}}}},"operationId":"registerAgent","tags":["Agents"],"parameters":[],"summary":"Register a new agent session","description":"Idempotent on session_id — re-registering with the same session returns the existing row with status flipped to active.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRegister"}}}}}},"/api/v1/agents/{id}/lane-limit":{"put":{"responses":{"200":{"description":"OK"}},"operationId":"setAgentLaneLimit","tags":["Agents"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Set an agent lane limit as its coordinator or operator","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"laneLimit":{"type":"integer","minimum":1,"maximum":100}},"required":["laneLimit"]}}}}}},"/api/v1/agents/{id}/repo-grants":{"get":{"responses":{"200":{"description":"OK"}},"operationId":"listAgentRepoGrants","tags":["Agents"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"List an agent's repository grants"},"post":{"responses":{"201":{"description":"Created"}},"operationId":"grantAgentRepo","tags":["Agents"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Grant an agent access to another repository","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"repo":{"type":"string","minLength":1,"maxLength":300}},"required":["repo"]}}}}}},"/api/v1/agents/{id}/repo-grants/{grantId}/revoke":{"post":{"responses":{"200":{"description":"OK"}},"operationId":"revokeAgentRepo","tags":["Agents"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true},{"in":"path","name":"grantId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Revoke an agent repository grant"}},"/api/v1/agents/{id}/heartbeat":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Agent"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"heartbeatAgent","tags":["Agents"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Bump last_seen_at"}},"/api/v1/agents/{id}/disconnect":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Agent"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"disconnectAgent","tags":["Agents"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark an agent as disconnected"}},"/api/v1/agents/{id}/wakeup-result":{"post":{"responses":{"201":{"description":"Wakeup result recorded","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentWakeupResult"}},"required":["data"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"recordAgentWakeupResult","tags":["Agents"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Record a scheduler-triggered wakeup outcome","description":"the agent calls this at the end of every wakeup. Also bumps last_seen_at (equivalent to heartbeat semantically). The status enum drives the scheduler's next-tick cadence.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["in_progress","compiling","testing","awaiting_review","blocked","complete","released","failed-validation"]},"commitSha":{"type":["string","null"]},"notes":{"type":["string","null"]},"nextWakeupHint":{"type":["string","null"],"enum":["normal","fast","slow","awaiting-external",null]}},"required":["status"]}}}}}},"/api/v1/agents/{id}/ceiling":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"},"personId":{"type":["string","null"]},"permissionKeys":{"type":"array","items":{"type":"string"}},"explicitExclusions":{"type":"array","items":{"type":"string"}},"snapshotAt":{"type":"string"}},"required":["agentId","personId","permissionKeys","explicitExclusions","snapshotAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getAgentPermissionCeiling","tags":["Agents"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get an agent's effective permission ceiling","description":"Intersection of the linked person's observed permissions and the app grant. Release promotion is always explicitly excluded."}},"/api/v1/agents/{id}/wakeup-results":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentWakeupResult"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listAgentWakeupResults","tags":["Agents"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"List recent wakeup results for an agent","description":"Ordered by at desc. Default limit 50."}},"/api/v1/agents/{id}/wakeup-result/latest":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentWakeupResult"}},"required":["data"]}}}},"404":{"description":"Agent has no wakeup results yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getLatestAgentWakeupResult","tags":["Agents"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get the most recent wakeup result for an agent","description":"Convenience for the scheduler: 'what was this agent's last status?' in one read."}},"/api/v1/agents/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Agent"}],"properties":{"personDisplayName":{"type":"object","properties":{"value":{"type":["string","null"]},"masked":{"type":"boolean"},"hint":{"type":["string","null"]}},"required":["value","masked","hint"]}},"required":["personDisplayName"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getAgent","tags":["Agents"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get an agent by id"}},"/api/v1/people":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"subjectId":{"type":"string"},"membershipId":{"type":["string","null"]},"roleKeys":{"type":"array","items":{"type":"string"}},"roleLabels":{"type":"array","items":{"type":"string"}},"permissionKeys":{"type":"array","items":{"type":"string"}},"membershipStatus":{"type":["string","null"]},"namesSnapshotAt":{"type":["string","null"]},"firstSeenAt":{"type":"string"},"lastSeenAt":{"type":"string"},"displayName":{"type":"object","properties":{"value":{"type":["string","null"]},"masked":{"type":"boolean"},"hint":{"type":["string","null"]}},"required":["value","masked","hint"]},"namesSource":{"type":"string","enum":["cache","unavailable"]},"namesAgeMs":{"type":["integer","null"],"minimum":0},"snapshotAt":{"type":["string","null"]},"agentsActive":{"type":"integer","minimum":0},"liveClaims":{"type":"integer","minimum":0},"isSelf":{"type":"boolean"}},"required":["subjectId","membershipId","roleKeys","roleLabels","permissionKeys","membershipStatus","namesSnapshotAt","firstSeenAt","lastSeenAt","displayName","namesSource","namesAgeMs","snapshotAt","agentsActive","liveClaims","isSelf"]}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listPeople","tags":["People"],"parameters":[{"in":"query","name":"role","schema":{"type":"string","minLength":1}},{"in":"query","name":"active","schema":{"type":"string","enum":["true","false"]}}],"summary":"List observed Dev people","description":"Viewer-aware local projection of staff observed through signed edge requests. Other people's names are masked server-side."}},"/api/v1/people/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"subjectId":{"type":"string"},"membershipId":{"type":["string","null"]},"roleKeys":{"type":"array","items":{"type":"string"}},"roleLabels":{"type":"array","items":{"type":"string"}},"permissionKeys":{"type":"array","items":{"type":"string"}},"membershipStatus":{"type":["string","null"]},"namesSnapshotAt":{"type":["string","null"]},"firstSeenAt":{"type":"string"},"lastSeenAt":{"type":"string"},"displayName":{"type":"object","properties":{"value":{"type":["string","null"]},"masked":{"type":"boolean"},"hint":{"type":["string","null"]}},"required":["value","masked","hint"]},"namesSource":{"type":"string","enum":["cache","unavailable"]},"namesAgeMs":{"type":["integer","null"],"minimum":0},"snapshotAt":{"type":["string","null"]},"isSelf":{"type":"boolean"},"agents":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}},"activeClaims":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["issue","feature_doc","request","slice"]},"id":{"type":"string"},"label":{"type":"string"},"agentId":{"type":["string","null"],"format":"uuid"},"expiresAt":{"type":["string","null"]}},"required":["kind","id","label","agentId","expiresAt"]}},"recentActivity":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"targetKind":{"type":"string"},"targetId":{"type":["string","null"]},"at":{"type":"string"}},"required":["action","targetKind","targetId","at"]}},"permissions":{"type":"array","items":{"type":"string"}}},"required":["subjectId","membershipId","roleKeys","roleLabels","permissionKeys","membershipStatus","namesSnapshotAt","firstSeenAt","lastSeenAt","displayName","namesSource","namesAgeMs","snapshotAt","isSelf","agents","activeClaims","recentActivity","permissions"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getPerson","tags":["People"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Get an observed Dev person"}},"/api/v1/people/{id}/reveal-name":{"post":{"responses":{"200":{"description":"Revealed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"value":{"type":["string","null"]},"masked":{"type":"boolean"},"hint":{"type":["string","null"]}},"required":["value","masked","hint"]}},"required":["data"]}}}}},"operationId":"revealPersonName","tags":["People"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Reveal one person's name","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"]}}}}}},"/api/v1/people/refresh-names":{"post":{"responses":{"200":{"description":"Refresh attempted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"namesSource":{"type":"string","enum":["cache","unavailable"]},"snapshotAt":{"type":["string","null"]},"ageMs":{"type":["integer","null"],"minimum":0},"refreshed":{"type":"integer","minimum":0},"reason":{"type":"string","enum":["unconfigured","forbidden","unavailable"]}},"required":["namesSource","snapshotAt","ageMs","refreshed"]}},"required":["data"]}}}}},"operationId":"refreshPeopleNames","tags":["People"],"parameters":[],"summary":"Refresh people names from tenant role holders","description":"Staff-only refresh. The route policy requires devops.agents.write; unavailable peer configuration is reported honestly."}},"/api/v1/doctrine":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GlobalDoctrine"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listDoctrine","tags":["Doctrine"],"parameters":[{"in":"query","name":"kind","schema":{"type":"string","enum":["global","workflow","module"]}},{"in":"query","name":"path_prefix","schema":{"type":"string"}},{"in":"query","name":"include_superseded","schema":{"type":"string","enum":["true","false"]}},{"in":"query","name":"include_deprecated","schema":{"type":"string","enum":["true","false"]}}],"summary":"List doctrine","description":"Returns latest version per path by default, including optional scope, enforcement and decisionRefs metadata. Pass include_superseded=true to get every row."},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GlobalDoctrine"}},"required":["data"]}}}},"409":{"description":"Path already exists — use /revise instead","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createDoctrine","tags":["Doctrine"],"parameters":[],"summary":"Create v1 of a new doctrine doc","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","minLength":1},"title":{"type":"string","minLength":1},"kind":{"type":"string","enum":["global","workflow","module"]},"scope":{"type":["string","null"],"minLength":1},"enforcement":{"type":["string","null"],"minLength":1},"decisionRefs":{"type":"array","items":{"type":"string","minLength":1},"maxItems":100},"bodyMd":{"type":"string","minLength":1},"sourceSha":{"type":["string","null"]}},"required":["path","title","kind","bodyMd"]}}}}}},"/api/v1/doctrine/{id}/deprecate":{"post":{"responses":{"200":{"description":"Deprecated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GlobalDoctrine"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deprecateDoctrine","tags":["Doctrine"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Soft-retire a doctrine row (excluded from the default list)","description":"Marks a doctrine row deprecated (e.g. an orphan from a defunct numbering scheme). It drops out of the default list but stays fetchable by id and recoverable. Idempotent.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1}},"required":["reason"]}}}}}},"/api/v1/doctrine/by-path/{path}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GlobalDoctrine"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getDoctrineByPath","tags":["Doctrine"],"parameters":[{"in":"path","name":"path","schema":{"type":"string","minLength":1},"required":true}],"summary":"Get latest doctrine revision by path"}},"/api/v1/doctrine/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GlobalDoctrine"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getDoctrine","tags":["Doctrine"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a specific doctrine revision"}},"/api/v1/doctrine/{id}/revise":{"post":{"responses":{"201":{"description":"Revised","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GlobalDoctrine"}},"required":["data"]}}}},"404":{"description":"Source doctrine row not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"reviseDoctrine","tags":["Doctrine"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Create v(N+1) of an existing doctrine doc","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1},"scope":{"type":["string","null"],"minLength":1},"enforcement":{"type":["string","null"],"minLength":1},"decisionRefs":{"type":"array","items":{"type":"string","minLength":1},"maxItems":100},"bodyMd":{"type":"string","minLength":1},"sourceSha":{"type":["string","null"]}},"required":["bodyMd"]}}}}}},"/api/v1/decisions":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Decision"}],"properties":{"amends":{"type":"array","items":{"type":"string"}},"buildsOn":{"type":"array","items":{"type":"string"}},"codificationState":{"type":"string","enum":["codified","debt","unknown","superseded"]}},"required":["amends","buildsOn","codificationState"]}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listDecisions","tags":["Decisions"],"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":500}},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0}},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["pending","locked","superseded"]},{"type":"array","items":{"type":"string","enum":["pending","locked","superseded"]}}]}},{"in":"query","name":"module","schema":{"type":"string"}},{"in":"query","name":"tag","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"since","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"includeSuperseded","schema":{"type":"string","enum":["true","false"]}}],"summary":"List decisions","description":"Superseded (dead) decisions are EXCLUDED by default — the agent-facing read only serves in-force decisions. Auditors opt in with `includeSuperseded=true`, or filter explicitly with `status=superseded`. Each row includes reverse `amends` ids and supersession-derived `buildsOn` ids."},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Decision"}},"required":["data"]}}}},"409":{"description":"Decision id already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createDecision","tags":["Decisions"],"parameters":[],"summary":"Create a decision","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^([a-z][a-z0-9_-]*-)?D\\d+$"},"title":{"type":"string","minLength":1},"module":{"type":"string","minLength":1},"topicTags":{"type":"array","items":{"type":"string"},"default":[]},"status":{"type":"string","enum":["pending","locked","superseded"],"default":"pending"},"bodyMd":{"type":"string","minLength":1},"supersedesId":{"type":["string","null"]},"lockedAt":{"type":["string","null"],"format":"date-time"},"autoLock":{"type":"boolean"}},"required":["id","title","module","bodyMd"]}}}}}},"/api/v1/decisions/codification-debt":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","minimum":0},"unknownCount":{"type":"integer","minimum":0},"evidenceSince":{"type":"string","format":"date-time"},"computedAt":{"type":"string","format":"date-time"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"lockedAt":{"type":"string","format":"date-time"},"ageSeconds":{"type":"integer","minimum":0}},"required":["id","title","lockedAt","ageSeconds"]}},"nextCursor":{"type":["string","null"]}},"required":["count","unknownCount","evidenceSince","computedAt","items","nextCursor"]}}}}},"operationId":"getDecisionCodificationDebt","tags":["Decisions"],"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"in":"query","name":"cursor","schema":{"type":"string","maxLength":500}}],"summary":"Get decision codification debt","description":"Counts uncited, non-superseded locked decisions since decisionRefs evidence began. Older uncited locks are reported separately as unknown. Items are oldest-first and keyset-paginated."}},"/api/v1/decisions/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Decision"}],"properties":{"bodyMd":{"type":"string"},"amendments":{"type":"array","items":{"$ref":"#/components/schemas/DecisionAmendment"}},"amends":{"type":"array","items":{"type":"string"}},"buildsOn":{"type":"array","items":{"type":"string"}},"codification":{"type":"object","properties":{"state":{"type":"string","enum":["codified","debt","unknown","superseded"]},"citedBy":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["feature_doc","doctrine"]},"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"version":{"type":"integer","exclusiveMinimum":0}},"required":["kind","id","key","version"]}}},"required":["state","citedBy"]}},"required":["bodyMd","amendments","amends","buildsOn","codification"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getDecision","tags":["Decisions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^(([a-z][a-z0-9_-]*-)?D\\d+|DEC-\\d{4,})$"},"required":true},{"in":"query","name":"includeSuperseded","schema":{"type":"string","enum":["true","false"]}}],"summary":"Get a decision by id","description":"A dead (superseded / future tombstoned) decision returns a one-line tombstone body by default — its full dead text is never fed to an agent unless the auditor passes `includeSuperseded=true`. The original body is preserved in object storage; the collapse is applied at read time only. `amendments` lists the append-only amendment notes (POST /decisions/:id/amendments), oldest first; the stored body is never rewritten to carry them."},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Decision"}},"required":["data"]}}}},"403":{"description":"Non-operator tried to lock via PATCH","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"DECISION_LOCKED (ruling field on a locked/superseded decision) or DECISION_SUPERSEDE_VIA_ROUTE (status=superseded via PATCH)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateDecision","tags":["Decisions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^(([a-z][a-z0-9_-]*-)?D\\d+|DEC-\\d{4,})$"},"required":true}],"summary":"Update a decision","description":"A `pending` decision may be edited freely (title, module, topicTags, bodyMd). A `locked` or `superseded` decision is IMMUTABLE: `title`, `bodyMd` and `status` are refused with 409 `DECISION_LOCKED`; only the catalog metadata `module` and `topicTags` may change. Record a later ruling against a locked decision with POST /decisions/:id/amendments. `status` cannot be set to `superseded` here (use /supersede), and setting `locked` is operator-only, exactly as POST /decisions/:id/lock.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1},"module":{"type":"string","minLength":1},"topicTags":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["pending","locked","superseded"]},"bodyMd":{"type":"string","minLength":1}}}}}}}},"/api/v1/decisions/{id}/amendments":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DecisionAmendment"}},"required":["data"]}}}},"404":{"description":"Target decision not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Target decision is not locked (DECISION_NOT_LOCKED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Amending decision missing / not locked / same as target (AMENDING_DECISION_NOT_FOUND, AMENDING_DECISION_NOT_LOCKED, DECISION_SELF_AMENDMENT)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createDecisionAmendment","tags":["Decisions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^(([a-z][a-z0-9_-]*-)?D\\d+|DEC-\\d{4,})$"},"required":true}],"summary":"Append an amendment note to a locked decision","description":"The sanctioned way to record that a later LOCKED decision amends a locked one (PP-93, D1366). Appends a row to `decision_amendments`; the target's title, body and status are never changed. GET /decisions/:id returns the notes as `amendments`. The target must be `locked`; the amending decision must exist, be `locked`, and differ from the target.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amendedByDecisionId":{"type":"string","pattern":"^([a-z][a-z0-9_-]*-)?D\\d+$"},"note":{"type":"string","minLength":1,"maxLength":4000}},"required":["amendedByDecisionId","note"]}}}}}},"/api/v1/decisions/{id}/lock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Decision"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Cannot lock a superseded decision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"lockDecision","tags":["Decisions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^(([a-z][a-z0-9_-]*-)?D\\d+|DEC-\\d{4,})$"},"required":true}],"summary":"Transition a decision to locked","description":"**Step 2 of the two-step workflow**: after creating a decision via POST /decisions (which creates it as `pending`), call this endpoint to lock it. Once locked, the decision is immutable and can be referenced from drift entries, feature_docs, and requests. To skip the two-step flow entirely, use `autoLock: true` on POST /decisions.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"lockedAt":{"type":"string","format":"date-time"}}}}}}}},"/api/v1/decisions/{id}/supersede":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Decision"}},"required":["data"]}}}},"404":{"description":"Source not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"New decision id already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"supersedeDecision","tags":["Decisions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^(([a-z][a-z0-9_-]*-)?D\\d+|DEC-\\d{4,})$"},"required":true}],"summary":"Create a new decision that supersedes this one","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"newId":{"type":"string","pattern":"^([a-z][a-z0-9_-]*-)?D\\d+$"},"newTitle":{"type":"string","minLength":1},"newBodyMd":{"type":"string","minLength":1},"newTopicTags":{"type":"array","items":{"type":"string"}}},"required":["newId","newTitle","newBodyMd"]}}}}}},"/api/v1/feature-docs":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FeatureDoc"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listFeatureDocs","tags":["FeatureDocs"],"parameters":[{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["planned","approved","implementing","partially_implemented","implemented","superseded"]},{"type":"array","items":{"type":"string","enum":["planned","approved","implementing","partially_implemented","implemented","superseded"]}}]}},{"in":"query","name":"docKey","schema":{"type":"string"}},{"in":"query","name":"include_superseded","schema":{"type":"string","enum":["true","false"]}},{"in":"query","name":"claimed_by","schema":{"type":"string","format":"uuid"}}],"summary":"List feature docs (latest per (serviceId, docKey) by default)","description":"Includes optional area and decisionRefs metadata for each feature document."},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FeatureDoc"}},"required":["data"]}}}},"409":{"description":"(serviceId, docKey) already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Required H1 sections missing from body_md","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createFeatureDoc","tags":["FeatureDocs"],"parameters":[],"summary":"Create v1 of a feature doc","description":"Accepts optional area and decisionRefs metadata alongside the canonical body.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"serviceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"docKey":{"type":"string","pattern":"^[a-z][a-z0-9-]*$"},"title":{"type":"string","minLength":1},"area":{"type":["string","null"],"minLength":1},"decisionRefs":{"type":"array","items":{"type":"string","minLength":1},"maxItems":100},"bodyMd":{"type":"string","minLength":1}},"required":["serviceId","docKey","title","bodyMd"]}}}}}},"/api/v1/feature-docs/by-key/{serviceId}/{docKey}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FeatureDoc"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getFeatureDocByKey","tags":["FeatureDocs"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true},{"in":"path","name":"docKey","schema":{"type":"string","pattern":"^[a-z][a-z0-9-]*$"},"required":true}],"summary":"Get latest feature doc revision for (serviceId, docKey)"}},"/api/v1/feature-docs/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FeatureDoc"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getFeatureDoc","tags":["FeatureDocs"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a specific feature doc revision by id"}},"/api/v1/feature-docs/{id}/revise":{"post":{"responses":{"201":{"description":"Revised","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FeatureDoc"}},"required":["data"]}}}},"404":{"description":"Source revision not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"A later revision already exists; revise the new latest instead","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Required H1 sections missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"reviseFeatureDoc","tags":["FeatureDocs"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Create v(N+1) of a feature doc","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1},"area":{"type":["string","null"],"minLength":1},"decisionRefs":{"type":"array","items":{"type":"string","minLength":1},"maxItems":100},"bodyMd":{"type":"string","minLength":1}},"required":["bodyMd"]}}}}}},"/api/v1/feature-docs/{id}/claim":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FeatureDoc"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Lease held by another agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Cannot claim a feature doc that is not approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"claimFeatureDoc","tags":["FeatureDocs"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Lease a feature doc for implementation","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ttlMinutes":{"type":"integer","exclusiveMinimum":0,"maximum":1440}}}}}}}},"/api/v1/feature-docs/{id}/renew-claim":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FeatureDoc"}},"required":["data"]}}}},"403":{"description":"Lease not held by this agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"renewFeatureDocClaim","tags":["FeatureDocs"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Renew an existing claim's TTL","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ttlMinutes":{"type":"integer","exclusiveMinimum":0,"maximum":1440}}}}}}}},"/api/v1/feature-docs/{id}/release":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FeatureDoc"}},"required":["data"]}}}},"403":{"description":"Lease not held by this agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"releaseFeatureDocClaim","tags":["FeatureDocs"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Release a claim without completing"}},"/api/v1/feature-docs/{id}/complete":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FeatureDoc"}},"required":["data"]}}}},"403":{"description":"Lease not held","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"completeFeatureDoc","tags":["FeatureDocs"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a feature doc as implemented with the commit SHA","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"commitSha":{"type":"string","pattern":"^[0-9a-f]{7,40}$"}},"required":["commitSha"]}}}}}},"/api/v1/feature-docs/{id}/approve":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FeatureDoc"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Not in planned state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"approveFeatureDoc","tags":["FeatureDocs"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Transition planned → approved","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"approvedBy":{"type":"string"}}}}}}}},"/api/v1/feature-docs/{id}/status":{"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FeatureDoc"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"patchFeatureDocStatus","tags":["FeatureDocs"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update status (and optionally completionPct) of a feature doc","description":"Allows impl sessions to reconcile Dev status against real code state. Use status=partially_implemented + completionPct to show incremental progress.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["planned","approved","implementing","partially_implemented","implemented","superseded"]},"completionPct":{"type":["integer","null"],"minimum":0,"maximum":100},"commitSha":{"type":"string","pattern":"^[0-9a-f]{7,40}$"}},"required":["status"]}}}}}},"/api/v1/feature-docs/status-batch":{"post":{"responses":{"200":{"description":"OK — returns updated rows (missing ids silently skipped)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FeatureDoc"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"batchPatchFeatureDocStatus","tags":["FeatureDocs"],"parameters":[],"summary":"Batch-update status for up to 200 feature docs in one transaction","description":"Designed for the impl-session reconciliation pass: load current code state, diff against Dev statuses, patch all mismatches in one call.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"patches":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["planned","approved","implementing","partially_implemented","implemented","superseded"]},"completionPct":{"type":["integer","null"],"minimum":0,"maximum":100},"commitSha":{"type":"string","pattern":"^[0-9a-f]{7,40}$"}},"required":["id","status"]},"minItems":1,"maxItems":200}},"required":["patches"]}}}}}},"/api/v1/sagas":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Saga"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listSagas","tags":["Sagas"],"parameters":[{"in":"query","name":"orchestratorServiceId","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["planned","implemented","deprecated"]},{"type":"array","items":{"type":"string","enum":["planned","implemented","deprecated"]}}]}},{"in":"query","name":"involvesServiceId","schema":{"type":"string"}}],"summary":"List sagas"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Saga"}],"properties":{"steps":{"type":"array","items":{"$ref":"#/components/schemas/SagaStep"}}},"required":["steps"]}},"required":["data"]}}}},"409":{"description":"Saga name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createSaga","tags":["Sagas"],"parameters":[],"summary":"Create a saga (optionally with steps)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"orchestratorServiceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"descriptionMd":{"type":"string","minLength":1},"status":{"type":"string","enum":["planned","implemented","deprecated"]},"steps":{"type":"array","items":{"type":"object","properties":{"callsServiceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"callsRpc":{"type":"string","minLength":1},"compensationRpc":{"type":["string","null"]},"sync":{"type":"boolean"},"description":{"type":["string","null"]}},"required":["callsServiceId","callsRpc"]}}},"required":["name","orchestratorServiceId","descriptionMd"]}}}}}},"/api/v1/sagas/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Saga"}],"properties":{"steps":{"type":"array","items":{"$ref":"#/components/schemas/SagaStep"}}},"required":["steps"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getSaga","tags":["Sagas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a saga with embedded steps"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Saga"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateSaga","tags":["Sagas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update saga metadata","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"descriptionMd":{"type":"string","minLength":1},"status":{"type":"string","enum":["planned","implemented","deprecated"]}}}}}}},"delete":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Saga"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deprecateSaga","tags":["Sagas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Soft-delete (status=deprecated)"}},"/api/v1/sagas/{id}/steps":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SagaStep"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listSagaSteps","tags":["Sagas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"List steps for a saga"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SagaStep"}},"required":["data"]}}}},"404":{"description":"Saga not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"appendSagaStep","tags":["Sagas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Append a step to a saga","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"callsServiceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"callsRpc":{"type":"string","minLength":1},"compensationRpc":{"type":["string","null"]},"sync":{"type":"boolean"},"description":{"type":["string","null"]}},"required":["callsServiceId","callsRpc"]}}}}}},"/api/v1/sagas/{id}/implement":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Saga"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"implementSaga","tags":["Sagas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a saga as implemented","description":"Use after the orchestrator code is shipped + tested against the real backing stack per R1. Pairs with contract-lifecycle-progression skill."}},"/api/v1/sagas/{id}/steps/{stepId}":{"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SagaStep"}},"required":["data"]}}}},"404":{"description":"Step not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateSagaStep","tags":["Sagas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true},{"in":"path","name":"stepId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update a step","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"callsServiceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"callsRpc":{"type":"string","minLength":1},"compensationRpc":{"type":["string","null"]},"sync":{"type":"boolean"},"description":{"type":["string","null"]}}}}}}},"delete":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"removed":{"type":"string","format":"uuid"}},"required":["removed"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"removeSagaStep","tags":["Sagas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true},{"in":"path","name":"stepId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Remove a step (reorders remaining)"}},"/api/v1/sagas/{id}/reorder":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Saga"}],"properties":{"steps":{"type":"array","items":{"$ref":"#/components/schemas/SagaStep"}}},"required":["steps"]}},"required":["data"]}}}},"404":{"description":"Saga not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Order is not a valid permutation of existing steps","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"reorderSagaSteps","tags":["Sagas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Replace step ordering with a new permutation","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1}},"required":["order"]}}}}}},"/api/v1/sagas/{id}/lock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Saga"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"lockSaga","tags":["Sagas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Lock a saga's contract (freeze the minimum blueprint)","description":"Sets lockedAt/lockedByAgentId (+ optional lockedBySliceId). Orthogonal to status. Idempotent re-lock.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sliceId":{"type":"string","format":"uuid"}}}}}}}},"/api/v1/sagas/{id}/unlock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Saga"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unlockSaga","tags":["Sagas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Unlock a saga's contract (operator escape hatch)","description":"Clears lockedAt/lockedByAgentId/lockedBySliceId."}},"/api/v1/requests":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Request"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listRequests","tags":["Requests"],"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":500}},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0}},{"in":"query","name":"fromService","schema":{"type":"string"}},{"in":"query","name":"toService","schema":{"type":"string"}},{"in":"query","name":"serviceId","schema":{"type":"string"}},{"in":"query","name":"direction","schema":{"type":"string","enum":["inbound","outbound"]}},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["open","acknowledged","resolved","rejected"]},{"type":"array","items":{"type":"string","enum":["open","acknowledged","resolved","rejected"]}}]}},{"in":"query","name":"kind","schema":{"type":"string"}},{"in":"query","name":"includeExpired","schema":{"type":"string"}}],"summary":"List requests with filters"},"post":{"responses":{"201":{"description":"Created or existing returned","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Request"}},"required":["data"]}}}},"404":{"description":"Source or target service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"fileRequest","tags":["Requests"],"parameters":[],"summary":"File a cross-service request (idempotent on requestHash)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"requestHash":{"type":"string","pattern":"^[0-9a-f]{16}$"},"fromService":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"toService":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"kind":{"type":"string","minLength":1},"specMd":{"type":"string","minLength":1},"targetArtifactType":{"type":["string","null"]},"targetArtifactId":{"type":["string","null"]},"parentRequestId":{"type":["string","null"],"format":"uuid"},"requiredCapability":{"type":["string","null"]},"expiresAt":{"type":["string","null"],"format":"date-time"}},"required":["requestHash","fromService","toService","kind","specMd"]}}}}}},"/api/v1/requests/by-hash/{hash}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Request"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getRequestByHash","tags":["Requests"],"parameters":[{"in":"path","name":"hash","schema":{"type":"string","pattern":"^[0-9a-f]{16}$"},"required":true}],"summary":"Get a request by its request_hash"}},"/api/v1/requests/inbox/{serviceId}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Request"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"getRequestInbox","tags":["Requests"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["open","acknowledged"]},{"type":"array","items":{"type":"string","enum":["open","acknowledged"]}}]}}],"summary":"Pending requests targeting a service"}},"/api/v1/requests/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Request"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getRequest","tags":["Requests"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a request by id"}},"/api/v1/requests/{id}/acknowledge":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Request"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Invalid transition (not in 'open' status)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"acknowledgeRequest","tags":["Requests"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Acknowledge a request (open → acknowledged)"}},"/api/v1/requests/{id}/resolve":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Request"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Already resolved or rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"resolveRequest","tags":["Requests"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Resolve a request with a commit SHA","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"commitSha":{"type":"string","pattern":"^[0-9a-f]{7,40}$"},"resolutionMd":{"type":["string","null"]},"targetArtifactType":{"type":["string","null"]},"targetArtifactId":{"type":["string","null"]},"shippedVersion":{"type":["string","null"]}},"required":["commitSha"]}}}}}},"/api/v1/requests/{id}/reject":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Request"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"rejectRequest","tags":["Requests"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Reject a request with a reason","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"resolutionMd":{"type":"string","minLength":1}},"required":["resolutionMd"]}}}}}},"/api/v1/requests/{id}/claim":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Request"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Already claimed by another agent with a live lease","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Request is not in open/acknowledged status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"claimRequest","tags":["Requests"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Claim a request lease (prevents duplicate agent work)","description":"Acquires an exclusive lease on the request for the calling agent. Another agent may not claim the same request until the lease expires or is released. Pass ttlMinutes matching your expected work window (default 60).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ttlMinutes":{"type":"integer","minimum":1,"maximum":480}}}}}}}},"/api/v1/requests/{id}/release":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Request"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Caller is not the current claimant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"releaseRequest","tags":["Requests"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Release a previously claimed request lease"}},"/api/v1/requests/{id}/resolve-and-fan-out":{"post":{"responses":{"200":{"description":"OK — resolved row + count of fan-out notices filed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Request"},"fanOutCount":{"type":"number"}},"required":["data","fanOutCount"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Already resolved or rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"resolveAndFanOut","tags":["Requests"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Resolve a request and fan out inbox notices to sibling requestors","description":"Resolves the request and automatically files contract-vendor-ready-notice inbox messages to every open sibling request (same kind targeting the same service). Use this instead of plain /resolve when the resolution should propagate to services that filed related requests. Notices auto-expire in 30 days.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"commitSha":{"type":"string","pattern":"^[0-9a-f]{7,40}$"},"resolutionMd":{"type":["string","null"]},"shippedVersion":{"type":["string","null"]},"noticeKind":{"type":["string","null"]}},"required":["commitSha"]}}}}}},"/api/v1/audit-log":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditLog"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listAuditLog","tags":["AuditLog"],"parameters":[{"in":"query","name":"actor","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"actor_kind","schema":{"type":"string","enum":["agent","operator","system"]}},{"in":"query","name":"action","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"targetKind","schema":{"type":"string"}},{"in":"query","name":"targetId","schema":{"type":"string"}},{"in":"query","name":"since","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"until","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"limit","schema":{"type":"string","pattern":"^\\d+$"}},{"in":"query","name":"offset","schema":{"type":"string","pattern":"^\\d+$"}}],"summary":"List audit log entries with filters"}},"/api/v1/audit-log/by-target/{kind}/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditLog"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listAuditLogByTarget","tags":["AuditLog"],"parameters":[{"in":"path","name":"kind","schema":{"type":"string","minLength":1},"required":true},{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Chronological audit trail for a specific artifact"}},"/api/v1/audit-log/by-actor/{actor}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditLog"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listAuditLogByActor","tags":["AuditLog"],"parameters":[{"in":"path","name":"actor","schema":{"type":"string","minLength":1},"required":true},{"in":"query","name":"since","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"limit","schema":{"type":"string","pattern":"^\\d+$"}}],"summary":"Activity of a single actor"}},"/api/v1/audit-log/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AuditLog"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getAuditLogEntry","tags":["AuditLog"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get an audit log entry by id"}},"/api/v1/cron/tick":{"post":{"responses":{"201":{"description":"Tick recorded","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CronTick"}},"required":["data"]}}}}},"operationId":"recordCronTick","tags":["Cron"],"parameters":[],"summary":"Record a scheduler tick (liveness signal)","description":"Schedulers POST after each successful tick. External monitor reads `latest tick per name` and alerts on stale.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CronTickInsert"}}}}}},"/api/v1/cron/ticks/{name}/latest":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CronTick"}},"required":["data"]}}}},"404":{"description":"No ticks for this scheduler name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getLatestCronTickByName","tags":["Cron"],"parameters":[{"in":"path","name":"name","schema":{"type":"string","minLength":1,"maxLength":100},"required":true}],"summary":"Latest tick for a named scheduler"}},"/api/v1/cron/latest":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CronTick"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listLatestCronTicks","tags":["Cron"],"parameters":[],"summary":"Latest tick for every registered scheduler","description":"One row per distinct `name`. Dashboard for 'are all schedulers alive?'"}},"/api/v1/reconciliation/{kind}/{id}/mark-dirty":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReconciledContract"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"markContractDirty","tags":["Reconciliation"],"parameters":[{"in":"path","name":"kind","schema":{"type":"string","enum":["grpc-interface","rest-interface","outbox-topic","table","saga","approval-kind"]},"required":true},{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Flag a contract artifact dirty (needs reconciliation vs its impl)","description":"Sets reconciliation_state='dirty' + dirty_reason. Orthogonal to status/lock (a locked, implemented contract can be dirty). D378.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1}},"required":["reason"]}}}}}},"/api/v1/reconciliation/{kind}/{id}/reconcile":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReconciledContract"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"reconcileContract","tags":["Reconciliation"],"parameters":[{"in":"path","name":"kind","schema":{"type":"string","enum":["grpc-interface","rest-interface","outbox-topic","table","saga","approval-kind"]},"required":true},{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Reconcile a contract artifact clean (verified to match its impl)","description":"Sets reconciliation_state='clean', stamps reconciled_at/by, clears dirty_reason. Called by the impl agent after verifying the contract against code (verified-clean = reconciled_at set). D378.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string"}}}}}}}},"/api/v1/design/sync/catalog":{"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"syncDesignCatalog","tags":["Design"],"parameters":[],"summary":"Synchronize the design-system catalog","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string","minLength":1},"catalog":{"type":"object","properties":{"schema":{"type":"string","const":"nodii.design-catalog/v1"},"generatedFrom":{"type":"string","minLength":1},"figma":{"type":"object","properties":{"fileKey":{"type":"string"},"version":{"type":"string"},"lastModified":{"type":"string","format":"date-time"}},"required":["fileKey","version","lastModified"]},"groups":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["foundation","component","block","pattern"]},"key":{"type":"string"},"title":{"type":"string"},"ordinal":{"type":"integer"}},"required":["kind","key","title","ordinal"]}},"entries":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["foundation","component","block","pattern"]},"group":{"type":"string"},"parentKey":{"type":["string","null"]},"domain":{"type":["string","null"]},"switcherContext":{"type":["string","null"]},"module":{"type":["string","null"]},"status":{"type":"string","enum":["stable","beta","deprecated"]},"codePath":{"type":["string","null"]},"docsPath":{"type":["string","null"]},"figma":{"type":["object","null"],"properties":{"fileKey":{"type":"string"},"nodeId":{"type":"string"},"componentKey":{"type":"string"}},"required":["fileKey","nodeId","componentKey"]},"codeConnect":{"type":"boolean"},"variants":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"figmaNodeId":{"type":"string"}},"required":["name","figmaNodeId"]}},"slots":{"type":"array","items":{"type":"object","additionalProperties":{}}},"guidelines":{"type":"object","properties":{"path":{"type":["string","null"]},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"statement":{"type":"string"},"enforcement":{"type":"string","enum":["type","lint","validator","test","review","none"]},"enforcedBy":{"type":["string","null"]}},"required":["id","statement","enforcement","enforcedBy"]}}},"required":["path","rules"]},"consumers":{"type":["object","null"],"properties":{"switcherContexts":{"type":"array","items":{"type":"string"}},"modules":{"type":"array","items":{"type":"string"}},"measuredAt":{"type":"string","format":"date-time"},"source":{"type":"string"}},"required":["measuredAt","source"]},"pending":{"type":"object","properties":{"question":{"type":"string","pattern":"^Q-[0-9]+$"},"reason":{"type":"string","enum":["retire","leaving-for-surfaces"]},"destination":{"type":["string","null"]}},"required":["question","reason","destination"],"additionalProperties":false}},"required":["key","title","kind","group","parentKey","domain","status","codePath","docsPath","figma","codeConnect","variants","slots","guidelines","consumers"]}}},"required":["schema","generatedFrom","figma","groups","entries"]},"guidelines":{"type":["object","null"],"properties":{"entries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"guideline":{"oneOf":[{"type":"object","properties":{"whenToUse":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"whenNotToUse":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"dos":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"donts":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"status":{"type":"string","const":"active"},"anatomy":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"states":{"type":"object","properties":{"states":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"loading":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"empty":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"error":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]}},"required":["states","loading","empty","error"]},"copy":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"composition":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"data":{"type":"object","properties":{"binding":{"type":"string","enum":["presentational","connected"]},"endpoints":{"type":"array","items":{"type":"string"}},"notes":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]}},"required":["binding","endpoints","notes"]},"id":{"type":"string","minLength":1},"enforcement":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string","minLength":1},"by":{"type":"string","minLength":1}},"required":["rule","by"]}}},"required":["whenToUse","whenNotToUse","dos","donts","status","anatomy","states","copy","data","id","enforcement"]},{"type":"object","properties":{"whenToUse":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"whenNotToUse":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"dos":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"donts":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"status":{"type":"string","const":"parked"},"id":{"type":"string","minLength":1}},"required":["whenToUse","whenNotToUse","dos","donts","status","id"]}]},"enforcement":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string","minLength":1},"by":{"type":"string","minLength":1}},"required":["rule","by"]}}},"required":["id","guideline"]}}},"required":["entries"]}},"required":["ref","catalog"]}}}}}},"/api/v1/design/entries":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["foundation","component","block","pattern"]},"groupKey":{"type":"string"},"parentKey":{"type":["string","null"]},"domain":{"type":["string","null"]},"switcherContext":{"type":["string","null"]},"status":{"type":"string"},"codePath":{"type":["string","null"]},"docsPath":{"type":["string","null"]},"figmaFileKey":{"type":["string","null"]},"figmaNodeId":{"type":["string","null"]},"figmaComponentKey":{"type":["string","null"]},"codeConnect":{"type":"boolean"},"slots":{"type":"array","items":{"type":"object","additionalProperties":{}}},"consumers":{"type":["object","null"],"properties":{"switcherContexts":{"type":"array","items":{"type":"string"}},"measuredAt":{"type":"string"},"source":{"type":"string"}},"required":["switcherContexts","measuredAt","source"]},"pending":{"type":["object","null"],"properties":{"question":{"type":"string"},"reason":{"type":"string","enum":["retire","leaving-for-surfaces"]},"destination":{"type":["string","null"]}},"required":["question","reason","destination"]},"guidelineDraftedCount":{"type":"integer","minimum":0},"presentInCatalog":{"type":"boolean"},"firstSeenRun":{"type":["string","null"],"format":"uuid"},"lastSeenRun":{"type":["string","null"],"format":"uuid"},"parts":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["foundation","component","block","pattern"]},"groupKey":{"type":"string"},"parentKey":{"type":["string","null"]},"domain":{"type":["string","null"]},"switcherContext":{"type":["string","null"]},"status":{"type":"string"},"codePath":{"type":["string","null"]},"docsPath":{"type":["string","null"]},"figmaFileKey":{"type":["string","null"]},"figmaNodeId":{"type":["string","null"]},"figmaComponentKey":{"type":["string","null"]},"codeConnect":{"type":"boolean"},"slots":{"type":"array","items":{"type":"object","additionalProperties":{}}},"consumers":{"type":["object","null"],"properties":{"switcherContexts":{"type":"array","items":{"type":"string"}},"measuredAt":{"type":"string"},"source":{"type":"string"}},"required":["switcherContexts","measuredAt","source"]},"pending":{"type":["object","null"],"properties":{"question":{"type":"string"},"reason":{"type":"string","enum":["retire","leaving-for-surfaces"]},"destination":{"type":["string","null"]}},"required":["question","reason","destination"]},"guidelineDraftedCount":{"type":"integer","minimum":0},"presentInCatalog":{"type":"boolean"},"firstSeenRun":{"type":["string","null"],"format":"uuid"},"lastSeenRun":{"type":["string","null"],"format":"uuid"}},"required":["key","title","kind","groupKey","parentKey","domain","switcherContext","status","codePath","docsPath","figmaFileKey","figmaNodeId","figmaComponentKey","codeConnect","slots","consumers","pending","guidelineDraftedCount","presentInCatalog","firstSeenRun","lastSeenRun"]}}},"required":["key","title","kind","groupKey","parentKey","domain","switcherContext","status","codePath","docsPath","figmaFileKey","figmaNodeId","figmaComponentKey","codeConnect","slots","consumers","pending","guidelineDraftedCount","presentInCatalog","firstSeenRun","lastSeenRun","parts"]}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listDesignEntries","tags":["Design"],"parameters":[{"in":"query","name":"kind","schema":{"type":"string","enum":["foundation","component","block","pattern"]}},{"in":"query","name":"group","schema":{"type":"string"}},{"in":"query","name":"q","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string"}},{"in":"query","name":"hasDeviation","schema":{"type":"string","enum":["true","false"]}},{"in":"query","name":"guidelineDrafted","schema":{"type":"string","enum":["true","false"]}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"in":"query","name":"cursor","schema":{"type":"string"}}],"summary":"List tree-ready design entries"}},"/api/v1/design/entries/{key}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["foundation","component","block","pattern"]},"groupKey":{"type":"string"},"parentKey":{"type":["string","null"]},"domain":{"type":["string","null"]},"switcherContext":{"type":["string","null"]},"status":{"type":"string"},"codePath":{"type":["string","null"]},"docsPath":{"type":["string","null"]},"figmaFileKey":{"type":["string","null"]},"figmaNodeId":{"type":["string","null"]},"figmaComponentKey":{"type":["string","null"]},"codeConnect":{"type":"boolean"},"slots":{"type":"array","items":{"type":"object","additionalProperties":{}}},"consumers":{"type":["object","null"],"properties":{"switcherContexts":{"type":"array","items":{"type":"string"}},"measuredAt":{"type":"string"},"source":{"type":"string"}},"required":["switcherContexts","measuredAt","source"]},"pending":{"type":["object","null"],"properties":{"question":{"type":"string"},"reason":{"type":"string","enum":["retire","leaving-for-surfaces"]},"destination":{"type":["string","null"]}},"required":["question","reason","destination"]},"guidelineDraftedCount":{"type":"integer","minimum":0},"presentInCatalog":{"type":"boolean"},"firstSeenRun":{"type":["string","null"],"format":"uuid"},"lastSeenRun":{"type":["string","null"],"format":"uuid"},"guideline":{"oneOf":[{"type":"object","properties":{"whenToUse":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"whenNotToUse":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"dos":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"donts":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"status":{"type":"string","const":"active"},"anatomy":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"states":{"type":"object","properties":{"states":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"loading":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"empty":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"error":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]}},"required":["states","loading","empty","error"]},"copy":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"composition":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"data":{"type":"object","properties":{"binding":{"type":"string","enum":["presentational","connected"]},"endpoints":{"type":"array","items":{"type":"string"}},"notes":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]}},"required":["binding","endpoints","notes"]},"enforcement":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string","minLength":1},"by":{"type":"string","minLength":1}},"required":["rule","by"]}}},"required":["whenToUse","whenNotToUse","dos","donts","status","anatomy","states","copy","data","enforcement"]},{"type":"object","properties":{"whenToUse":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"whenNotToUse":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"dos":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"donts":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"status":{"type":"string","const":"parked"},"enforcement":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string","minLength":1},"by":{"type":"string","minLength":1}},"required":["rule","by"]}}},"required":["whenToUse","whenNotToUse","dos","donts","status","enforcement"]},{"type":"null"}]},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"entryKey":{"type":"string"},"name":{"type":"string"},"figmaNodeId":{"type":"string"},"currentImageId":{"type":["string","null"],"format":"uuid"}},"required":["id","entryKey","name","figmaNodeId","currentImageId"]}},"parts":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["foundation","component","block","pattern"]},"groupKey":{"type":"string"},"parentKey":{"type":["string","null"]},"domain":{"type":["string","null"]},"switcherContext":{"type":["string","null"]},"status":{"type":"string"},"codePath":{"type":["string","null"]},"docsPath":{"type":["string","null"]},"figmaFileKey":{"type":["string","null"]},"figmaNodeId":{"type":["string","null"]},"figmaComponentKey":{"type":["string","null"]},"codeConnect":{"type":"boolean"},"slots":{"type":"array","items":{"type":"object","additionalProperties":{}}},"consumers":{"type":["object","null"],"properties":{"switcherContexts":{"type":"array","items":{"type":"string"}},"measuredAt":{"type":"string"},"source":{"type":"string"}},"required":["switcherContexts","measuredAt","source"]},"pending":{"type":["object","null"],"properties":{"question":{"type":"string"},"reason":{"type":"string","enum":["retire","leaving-for-surfaces"]},"destination":{"type":["string","null"]}},"required":["question","reason","destination"]},"guidelineDraftedCount":{"type":"integer","minimum":0},"presentInCatalog":{"type":"boolean"},"firstSeenRun":{"type":["string","null"],"format":"uuid"},"lastSeenRun":{"type":["string","null"],"format":"uuid"},"guideline":{"oneOf":[{"type":"object","properties":{"whenToUse":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"whenNotToUse":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"dos":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"donts":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"status":{"type":"string","const":"active"},"anatomy":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"states":{"type":"object","properties":{"states":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"loading":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"empty":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"error":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]}},"required":["states","loading","empty","error"]},"copy":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"composition":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"data":{"type":"object","properties":{"binding":{"type":"string","enum":["presentational","connected"]},"endpoints":{"type":"array","items":{"type":"string"}},"notes":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]}},"required":["binding","endpoints","notes"]},"enforcement":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string","minLength":1},"by":{"type":"string","minLength":1}},"required":["rule","by"]}}},"required":["whenToUse","whenNotToUse","dos","donts","status","anatomy","states","copy","data","enforcement"]},{"type":"object","properties":{"whenToUse":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"whenNotToUse":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"dos":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"donts":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}},"provenance":{"type":"string","enum":["sourced","drafted"]},"refs":{"type":"array","items":{"type":"string"}}},"required":["items","provenance","refs"]},"status":{"type":"string","const":"parked"},"enforcement":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string","minLength":1},"by":{"type":"string","minLength":1}},"required":["rule","by"]}}},"required":["whenToUse","whenNotToUse","dos","donts","status","enforcement"]},{"type":"null"}]}},"required":["key","title","kind","groupKey","parentKey","domain","switcherContext","status","codePath","docsPath","figmaFileKey","figmaNodeId","figmaComponentKey","codeConnect","slots","consumers","pending","guidelineDraftedCount","presentInCatalog","firstSeenRun","lastSeenRun","guideline"]}},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"sourceKey":{"type":"string"},"entryKey":{"type":["string","null"]},"statement":{"type":"string"},"enforcement":{"type":"string"},"enforcedBy":{"type":["string","null"]},"textSha256":{"type":"string"},"status":{"type":"string","enum":["draft","locked","retired"]},"lockedTextSha256":{"type":["string","null"]},"lockedBy":{"type":["string","null"]},"lockedAt":{"type":["string","null"]},"supersededBy":{"type":["string","null"]}},"required":["id","sourceKey","entryKey","statement","enforcement","enforcedBy","textSha256","status","lockedTextSha256","lockedBy","lockedAt","supersededBy"]}},"deviations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["missing-in-catalog","missing-in-figma","missing-code","no-code-connect","ungrouped","no-consumers","single-module-block","single-context-block","locked-rule-changed","edit-outside-lock","vendored-drift","stale-image"]},"entryKey":{"type":["string","null"]},"ruleId":{"type":["string","null"]},"fileKey":{"type":["string","null"]},"detail":{"type":"object","additionalProperties":{}},"firstSeenRun":{"type":["string","null"],"format":"uuid"},"lastSeenRun":{"type":["string","null"],"format":"uuid"},"resolvedAt":{"type":["string","null"]}},"required":["id","kind","entryKey","ruleId","fileKey","detail","firstSeenRun","lastSeenRun","resolvedAt"]}},"changeSetHistory":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"changeSetId":{"type":"string"},"entryKey":{"type":["string","null"]},"figmaNodeId":{"type":"string"},"change":{"type":"string","enum":["changed","new","removed"]},"decision":{"type":"string","enum":["pending","approved","rejected"]},"comment":{"type":["string","null"]},"decidedBy":{"type":["string","null"]},"decidedAt":{"type":["string","null"]},"round":{"type":"integer","exclusiveMinimum":0}},"required":["id","changeSetId","entryKey","figmaNodeId","change","decision","comment","decidedBy","decidedAt","round"]}},"conflicts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"memberKeys":{"type":"array","items":{"type":"string"}},"description":{"type":"string"},"usage":{"type":"object","additionalProperties":{}},"proposedResolution":{"type":["string","null"]},"resolution":{"type":"string","enum":["open","merge","keep-distinct","move-to-surfaces","escalated"]},"resolvedBy":{"type":["string","null"]},"resolvedAt":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","title","memberKeys","description","usage","proposedResolution","resolution","resolvedBy","resolvedAt","createdAt"]}}},"required":["key","title","kind","groupKey","parentKey","domain","switcherContext","status","codePath","docsPath","figmaFileKey","figmaNodeId","figmaComponentKey","codeConnect","slots","consumers","pending","guidelineDraftedCount","presentInCatalog","firstSeenRun","lastSeenRun","guideline","variants","parts","rules","deviations","changeSetHistory","conflicts"]}},"required":["data"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getDesignEntry","tags":["Design"],"parameters":[{"in":"path","name":"key","schema":{"type":"string","minLength":1},"required":true}],"summary":"Get a design entry with its guideline"}},"/api/v1/design/guides/{key}":{"get":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"getDesignGuide","tags":["Design"],"parameters":[{"in":"path","name":"key","schema":{"type":"string","minLength":1},"required":true}],"summary":"Get the rules, pattern and blocks for a page type"}},"/api/v1/design/files":{"get":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"listDesignFiles","tags":["Design"],"parameters":[],"summary":"List design files"}},"/api/v1/design/change-sets":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"fileKey":{"type":"string"},"state":{"type":"string","enum":["editing","in_review","applying","awaiting_publish","published","abandoned"]},"baseVersion":{"type":["string","null"]},"submittedVersions":{"type":"array","items":{"type":"string"}},"approvedVersion":{"type":["string","null"]},"publishedVersion":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"closedAt":{"type":["string","null"]},"file":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["design-system","surfaces","prototype"]}},"required":["key","name","kind"]},"holder":{"type":"object","properties":{"person":{"type":["object","null"],"properties":{"id":{"type":"string"},"displayName":{"type":"object","properties":{"value":{"type":["string","null"]},"masked":{"type":"boolean"},"hint":{"type":["string","null"]}},"required":["value","masked","hint"]}},"required":["id","displayName"]},"agent":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"displayName":{"type":["string","null"]}},"required":["id","displayName"]}},"required":["person","agent"]},"itemCounts":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"decided":{"type":"integer","minimum":0},"approved":{"type":"integer","minimum":0},"rejected":{"type":"integer","minimum":0},"pending":{"type":"integer","minimum":0}},"required":["total","decided","approved","rejected","pending"]}},"required":["id","title","fileKey","state","baseVersion","submittedVersions","approvedVersion","publishedVersion","createdAt","updatedAt","closedAt","file","holder","itemCounts"]}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listDesignChangeSets","tags":["Design"],"parameters":[{"in":"query","name":"fileKey","schema":{"type":"string","minLength":1}},{"in":"query","name":"state","schema":{"anyOf":[{"type":"string","enum":["editing","in_review","applying","awaiting_publish","published","abandoned"]},{"type":"array","items":{"type":"string","enum":["editing","in_review","applying","awaiting_publish","published","abandoned"]}}]}},{"in":"query","name":"q","schema":{"type":"string","minLength":1}},{"in":"query","name":"sort","schema":{"type":"string","enum":["newest","oldest"],"default":"newest"}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0}}],"summary":"List design change sets"}},"/api/v1/design/change-sets/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"fileKey":{"type":"string"},"state":{"type":"string","enum":["editing","in_review","applying","awaiting_publish","published","abandoned"]},"baseVersion":{"type":["string","null"]},"submittedVersions":{"type":"array","items":{"type":"string"}},"approvedVersion":{"type":["string","null"]},"publishedVersion":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"closedAt":{"type":["string","null"]},"file":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["design-system","surfaces","prototype"]}},"required":["key","name","kind"]},"holder":{"type":"object","properties":{"person":{"type":["object","null"],"properties":{"id":{"type":"string"},"displayName":{"type":"object","properties":{"value":{"type":["string","null"]},"masked":{"type":"boolean"},"hint":{"type":["string","null"]}},"required":["value","masked","hint"]}},"required":["id","displayName"]},"agent":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"displayName":{"type":["string","null"]}},"required":["id","displayName"]}},"required":["person","agent"]},"itemCounts":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"decided":{"type":"integer","minimum":0},"approved":{"type":"integer","minimum":0},"rejected":{"type":"integer","minimum":0},"pending":{"type":"integer","minimum":0}},"required":["total","decided","approved","rejected","pending"]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"changeSetId":{"type":"string"},"entryKey":{"type":["string","null"]},"figmaNodeId":{"type":"string"},"change":{"type":"string","enum":["changed","new","removed"]},"decision":{"type":"string","enum":["pending","approved","rejected"]},"comment":{"type":["string","null"]},"decidedBy":{"type":["string","null"]},"decidedAt":{"type":["string","null"]},"round":{"type":"integer","exclusiveMinimum":0},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"itemId":{"type":"string","format":"uuid"},"figmaNodeId":{"type":"string"},"beforeImageId":{"type":["string","null"],"format":"uuid"},"afterImageId":{"type":["string","null"],"format":"uuid"}},"required":["id","itemId","figmaNodeId","beforeImageId","afterImageId"]}}},"required":["id","changeSetId","entryKey","figmaNodeId","change","decision","comment","decidedBy","decidedAt","round","variants"]}},"writeLog":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"changeSetId":{"type":"string"},"agentId":{"type":"string","format":"uuid"},"tool":{"type":"string"},"nodeIds":{"type":"array","items":{"type":"string"}},"at":{"type":"string"}},"required":["id","changeSetId","agentId","tool","nodeIds","at"]}}},"required":["id","title","fileKey","state","baseVersion","submittedVersions","approvedVersion","publishedVersion","createdAt","updatedAt","closedAt","file","holder","itemCounts","items","writeLog"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getDesignChangeSet","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Get a design change set with review items and write log"}},"/api/v1/design/files/{key}":{"get":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"getDesignFile","tags":["Design"],"parameters":[{"in":"path","name":"key","schema":{"type":"string","minLength":1},"required":true}],"summary":"Get a design file"}},"/api/v1/design/files/{key}/lock":{"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"claimDesignFileLock","tags":["Design"],"parameters":[{"in":"path","name":"key","schema":{"type":"string","minLength":1},"required":true}],"summary":"Claim a design file lock","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"changeSetTitle":{"type":"string","minLength":1}},"required":["changeSetTitle"]}}}}}},"/api/v1/design/files/{key}/lock/check":{"get":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"checkDesignFileLock","tags":["Design"],"parameters":[{"in":"path","name":"key","schema":{"type":"string","minLength":1},"required":true},{"in":"query","name":"agentId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Check whether an agent may write"}},"/api/v1/design/files/{key}/lock/release":{"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"forceReleaseDesignFileLock","tags":["Design"],"parameters":[{"in":"path","name":"key","schema":{"type":"string","minLength":1},"required":true}],"summary":"Force-release a design file lock"}},"/api/v1/design/change-sets/{id}/writes":{"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"logDesignWrite","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Log a Figma write","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string","minLength":1},"nodeIds":{"type":"array","items":{"type":"string"},"minItems":1}},"required":["tool","nodeIds"]}}}}}},"/api/v1/design/change-sets/{id}/submit":{"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"submitDesignChangeSet","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Submit a design change set","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"figmaVersion":{"type":"string","minLength":1},"items":{"type":"array","items":{"type":"object","properties":{"entryKey":{"type":"string"},"figmaNodeId":{"type":"string"},"change":{"type":"string","enum":["changed","new","removed"]},"variants":{"type":"array","items":{"type":"object","properties":{"nodeId":{"type":"string"},"beforePngBase64":{"type":"string"},"afterPngBase64":{"type":"string"}},"required":["nodeId"]}}},"required":["figmaNodeId","change","variants"]},"minItems":1}},"required":["figmaVersion","items"]}}}}}},"/api/v1/design/change-items/{id}/decide":{"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"decideDesignChangeItem","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Approve or reject a design item","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["approved","rejected"]},"comment":{"type":"string"}},"required":["decision"]}}}}}},"/api/v1/design/change-sets/{id}/apply":{"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"applyDesignChangeSet","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Record application of approved changes","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"figmaVersion":{"type":"string"}},"required":["figmaVersion"]}}}}}},"/api/v1/design/change-sets/{id}/published":{"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"publishDesignChangeSet","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Close a published change set","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"figmaVersion":{"type":"string"}},"required":["figmaVersion"]}}}}}},"/api/v1/design/change-sets/{id}/abandon":{"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"abandonDesignChangeSet","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Abandon a design change set"}},"/api/v1/design/rules":{"get":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"listDesignRules","tags":["Design"],"parameters":[],"summary":"List design rules"}},"/api/v1/design/rules/{id}":{"get":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"getDesignRule","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Get a design rule"}},"/api/v1/design/rules/{id}/lock":{"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"lockDesignRule","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"lock a design rule","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"supersededBy":{"type":"string"}}}}}}}},"/api/v1/design/rules/{id}/retire":{"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"retireDesignRule","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"retire a design rule","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"supersededBy":{"type":"string"}}}}}}}},"/api/v1/design/conflicts":{"get":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"listDesignConflicts","tags":["Design"],"parameters":[],"summary":"List design conflicts"},"post":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"createDesignConflict","tags":["Design"],"parameters":[],"summary":"Create a design conflict","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"memberKeys":{"type":"array","items":{"type":"string"},"minItems":2},"description":{"type":"string"},"usage":{"type":"object","additionalProperties":{},"default":{}},"proposedResolution":{"type":"string"}},"required":["title","memberKeys","description"]}}}}}},"/api/v1/design/conflicts/{id}":{"patch":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"updateDesignConflict","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Update a design conflict","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"usage":{"type":"object","additionalProperties":{}},"proposedResolution":{"type":["string","null"]},"resolution":{"type":"string","enum":["open","merge","keep-distinct","move-to-surfaces","escalated"]}}}}}}}},"/api/v1/design/deviations":{"get":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"listDesignDeviations","tags":["Design"],"parameters":[],"summary":"List design deviations"}},"/api/v1/design/images/{id}/raw":{"get":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"getDesignImageRaw","tags":["Design"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"Stream an immutable design PNG"}},"/api/v1/design/summary":{"get":{"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"}},"operationId":"getDesignSummary","tags":["Design"],"parameters":[],"summary":"Get design governance summary"}},"/api/v1/ideas":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"summary":{"type":"string"},"detail":{"type":["string","null"]},"status":{"type":"string","enum":["captured","exploring","promoted","dropped"]},"promotedLink":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","summary","detail","status","promotedLink","createdByAgentId","createdAt","updatedAt"]}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listIdeas","tags":["Ideas"],"parameters":[{"in":"query","name":"q","schema":{"type":"string","minLength":1}},{"in":"query","name":"status","schema":{"type":"string","enum":["captured","exploring","promoted","dropped"]}}],"summary":"List and search ideas"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"summary":{"type":"string"},"detail":{"type":["string","null"]},"status":{"type":"string","enum":["captured","exploring","promoted","dropped"]},"promotedLink":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","summary","detail","status","promotedLink","createdByAgentId","createdAt","updatedAt"]}},"required":["data"]}}}}},"operationId":"createIdea","tags":["Ideas"],"parameters":[],"summary":"Quick-capture an idea","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"string","minLength":1,"maxLength":280},"detail":{"type":"string","minLength":1}},"required":["summary"],"additionalProperties":false}}}}}},"/api/v1/ideas/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"summary":{"type":"string"},"detail":{"type":["string","null"]},"status":{"type":"string","enum":["captured","exploring","promoted","dropped"]},"promotedLink":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","summary","detail","status","promotedLink","createdByAgentId","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getIdea","tags":["Ideas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get an idea"}},"/api/v1/ideas/{id}/status":{"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"summary":{"type":"string"},"detail":{"type":["string","null"]},"status":{"type":"string","enum":["captured","exploring","promoted","dropped"]},"promotedLink":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","summary","detail","status","promotedLink","createdByAgentId","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateIdeaStatus","tags":["Ideas"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update an idea status","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["captured","exploring","promoted","dropped"]},"promotedLink":{"type":"string","format":"uri"}},"required":["status"],"additionalProperties":false}}}}}},"/api/v1/swaps":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fromPattern":{"type":"string"},"toPattern":{"type":"string"},"whyDecisionLink":{"type":"string"},"detectorKind":{"type":"string"},"detectorExpression":{"type":"string"},"guideLink":{"type":"string"},"examplePrLink":{"type":["string","null"]},"owner":{"type":"string"},"switcherContexts":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["open","closed"]},"closedAt":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"openSites":{"type":"integer"},"swappedSites":{"type":"integer"},"verifiedSites":{"type":"integer"},"totalSites":{"type":"integer"}},"required":["id","fromPattern","toPattern","whyDecisionLink","detectorKind","detectorExpression","guideLink","examplePrLink","owner","switcherContexts","status","closedAt","createdByAgentId","createdAt","updatedAt","openSites","swappedSites","verifiedSites","totalSites"]}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listSwaps","tags":["Swaps"],"parameters":[{"in":"query","name":"q","schema":{"type":"string","minLength":1}},{"in":"query","name":"status","schema":{"type":"string","enum":["open","closed"]}},{"in":"query","name":"switcherContext","schema":{"type":"string","minLength":1}}],"summary":"List swaps with progress counts"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fromPattern":{"type":"string"},"toPattern":{"type":"string"},"whyDecisionLink":{"type":"string"},"detectorKind":{"type":"string"},"detectorExpression":{"type":"string"},"guideLink":{"type":"string"},"examplePrLink":{"type":["string","null"]},"owner":{"type":"string"},"switcherContexts":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["open","closed"]},"closedAt":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","fromPattern","toPattern","whyDecisionLink","detectorKind","detectorExpression","guideLink","examplePrLink","owner","switcherContexts","status","closedAt","createdByAgentId","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createSwap","tags":["Swaps"],"parameters":[],"summary":"Declare an old to new swap","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fromPattern":{"type":"string","minLength":1},"toPattern":{"type":"string","minLength":1},"whyDecisionLink":{"type":"string","format":"uri"},"detectorKind":{"type":"string","enum":["grep","lint"]},"detectorExpression":{"type":"string","minLength":1},"guideLink":{"type":"string","format":"uri"},"examplePrLink":{"type":"string","format":"uri"},"owner":{"type":"string","minLength":1},"switcherContexts":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["fromPattern","toPattern","whyDecisionLink","detectorKind","detectorExpression","guideLink","owner","switcherContexts"],"additionalProperties":false}}}}}},"/api/v1/swaps/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fromPattern":{"type":"string"},"toPattern":{"type":"string"},"whyDecisionLink":{"type":"string"},"detectorKind":{"type":"string"},"detectorExpression":{"type":"string"},"guideLink":{"type":"string"},"examplePrLink":{"type":["string","null"]},"owner":{"type":"string"},"switcherContexts":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["open","closed"]},"closedAt":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"openSites":{"type":"integer"},"swappedSites":{"type":"integer"},"verifiedSites":{"type":"integer"},"totalSites":{"type":"integer"},"sites":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"swapId":{"type":"string","format":"uuid"},"repository":{"type":"string"},"filePath":{"type":["string","null"]},"line":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"route":{"type":["string","null"]},"switcherContext":{"type":["string","null"]},"status":{"type":"string","enum":["open","swapped","verified"]},"prLink":{"type":["string","null"]},"discoveredBy":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","swapId","repository","filePath","line","route","switcherContext","status","prLink","discoveredBy","createdAt","updatedAt"]}}},"required":["id","fromPattern","toPattern","whyDecisionLink","detectorKind","detectorExpression","guideLink","examplePrLink","owner","switcherContexts","status","closedAt","createdByAgentId","createdAt","updatedAt","openSites","swappedSites","verifiedSites","totalSites","sites"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getSwap","tags":["Swaps"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a swap, progress and sites"}},"/api/v1/swaps/{swapId}/sites":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"swapId":{"type":"string","format":"uuid"},"repository":{"type":"string"},"filePath":{"type":["string","null"]},"line":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"route":{"type":["string","null"]},"switcherContext":{"type":["string","null"]},"status":{"type":"string","enum":["open","swapped","verified"]},"prLink":{"type":["string","null"]},"discoveredBy":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","swapId","repository","filePath","line","route","switcherContext","status","prLink","discoveredBy","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createSwapSite","tags":["Swaps"],"parameters":[{"in":"path","name":"swapId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Record a site of an old pattern","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"repository":{"type":"string","minLength":1},"filePath":{"type":"string","minLength":1},"line":{"type":"integer","minimum":1},"route":{"type":"string","minLength":1},"switcherContext":{"type":"string","minLength":1},"discoveredBy":{"type":"string","enum":["detector","agent"],"default":"agent"}},"required":["repository"],"additionalProperties":false}}}}}},"/api/v1/swaps/sites/{id}/status":{"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"swapId":{"type":"string","format":"uuid"},"repository":{"type":"string"},"filePath":{"type":["string","null"]},"line":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"route":{"type":["string","null"]},"switcherContext":{"type":["string","null"]},"status":{"type":"string","enum":["open","swapped","verified"]},"prLink":{"type":["string","null"]},"discoveredBy":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","swapId","repository","filePath","line","route","switcherContext","status","prLink","discoveredBy","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateSwapSiteStatus","tags":["Swaps"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Move a swap site through open, swapped and verified","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["open","swapped","verified"]},"prLink":{"type":"string","format":"uri"}},"required":["status"],"additionalProperties":false}}}}}},"/api/v1/swaps/{id}/close":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fromPattern":{"type":"string"},"toPattern":{"type":"string"},"whyDecisionLink":{"type":"string"},"detectorKind":{"type":"string"},"detectorExpression":{"type":"string"},"guideLink":{"type":"string"},"examplePrLink":{"type":["string","null"]},"owner":{"type":"string"},"switcherContexts":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["open","closed"]},"closedAt":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","fromPattern","toPattern","whyDecisionLink","detectorKind","detectorExpression","guideLink","examplePrLink","owner","switcherContexts","status","closedAt","createdByAgentId","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"closeSwap","tags":["Swaps"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Close a swap when no open sites remain"}},"/api/v1/terminology":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"term":{"type":"string"},"definition":{"type":"string"},"not":{"type":"array","items":{"type":"string"}},"whereUsed":{"type":"array","items":{"type":"string"}},"bannedSynonyms":{"type":"array","items":{"type":"string"}},"source":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","term","definition","not","whereUsed","bannedSynonyms","source","createdAt","updatedAt"]}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listTerminology","tags":["Terminology"],"parameters":[{"in":"query","name":"q","schema":{"type":"string","minLength":1}},{"in":"query","name":"hasBannedSynonyms","schema":{"type":"string","enum":["true","false"]}}],"summary":"List and search global terminology"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"term":{"type":"string"},"definition":{"type":"string"},"not":{"type":"array","items":{"type":"string"}},"whereUsed":{"type":"array","items":{"type":"string"}},"bannedSynonyms":{"type":"array","items":{"type":"string"}},"source":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","term","definition","not","whereUsed","bannedSynonyms","source","createdAt","updatedAt"]}},"required":["data"]}}}},"409":{"description":"Term exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createTerminologyTerm","tags":["Terminology"],"parameters":[],"summary":"Create a terminology term","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"term":{"type":"string","minLength":1,"maxLength":120},"definition":{"type":"string","minLength":1},"not":{"type":"array","items":{"type":"string","minLength":1},"default":[]},"whereUsed":{"type":"array","items":{"type":"string","minLength":1},"default":[]},"bannedSynonyms":{"type":"array","items":{"type":"string","minLength":1},"default":[]},"source":{"type":["string","null"],"minLength":1}},"required":["term","definition"],"additionalProperties":false}}}}}},"/api/v1/terminology/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"term":{"type":"string"},"definition":{"type":"string"},"not":{"type":"array","items":{"type":"string"}},"whereUsed":{"type":"array","items":{"type":"string"}},"bannedSynonyms":{"type":"array","items":{"type":"string"}},"source":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","term","definition","not","whereUsed","bannedSynonyms","source","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getTerminologyTerm","tags":["Terminology"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a terminology term"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"term":{"type":"string"},"definition":{"type":"string"},"not":{"type":"array","items":{"type":"string"}},"whereUsed":{"type":"array","items":{"type":"string"}},"bannedSynonyms":{"type":"array","items":{"type":"string"}},"source":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","term","definition","not","whereUsed","bannedSynonyms","source","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateTerminologyTerm","tags":["Terminology"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update a terminology term","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"term":{"type":"string","minLength":1,"maxLength":120},"definition":{"type":"string","minLength":1},"not":{"type":"array","items":{"type":"string","minLength":1},"default":[]},"whereUsed":{"type":"array","items":{"type":"string","minLength":1},"default":[]},"bannedSynonyms":{"type":"array","items":{"type":"string","minLength":1},"default":[]},"source":{"type":["string","null"],"minLength":1}},"additionalProperties":false}}}}}},"/api/v1/documents":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdDocumentSummary"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listAdDocuments","tags":["ad-documents"],"parameters":[{"in":"query","name":"section","schema":{"type":"string","enum":["rulebook","services"]}},{"in":"query","name":"kind","schema":{"anyOf":[{"type":"string","enum":["principles","methodology","standard","doctrine","ux-guideline","know-how","feature-doc","service-overview","capability-plan"]},{"type":"array","items":{"type":"string","enum":["principles","methodology","standard","doctrine","ux-guideline","know-how","feature-doc","service-overview","capability-plan"]}}]}},{"in":"query","name":"serviceId","schema":{"type":"string","minLength":1,"maxLength":200}},{"in":"query","name":"domain","schema":{"type":"string","minLength":1,"maxLength":300}},{"in":"query","name":"status","schema":{"type":"string","enum":["draft","ratified"]}},{"in":"query","name":"q","schema":{"type":"string","minLength":1,"maxLength":200}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0}}],"summary":"List AD documents (rulebook and feature docs)"}},"/api/v1/documents/parked":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ParkedAcknowledgement"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listParkedAcknowledgements","tags":["ad-documents"],"parameters":[{"in":"query","name":"status","schema":{"type":"string","enum":["pending","acknowledged"],"default":"pending"}}],"summary":"Parked-item lists awaiting (or given) operator acknowledgement"}},"/api/v1/documents/validate":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean"},"documents":{"type":"array","items":{"type":"object","properties":{"path":{"type":["string","null"]},"code":{"type":["string","null"]},"version":{"type":["string","null"]},"changeClass":{"type":"string"},"kind":{"type":["string","null"]},"domain":{"type":["string","null"]},"clauseCount":{"type":"integer"},"parkedCount":{"type":"integer"},"parkedAcknowledged":{"type":"boolean"},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"line":{"type":"integer"}},"required":["code","message"]}},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"line":{"type":"integer"}},"required":["code","message"]}}},"required":["path","code","version","changeClass","kind","domain","clauseCount","parkedCount","parkedAcknowledged","errors","warnings"]}},"decisionErrors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}},"required":["ok","documents","decisionErrors"]}},"required":["data"]}}}}},"operationId":"validateAdDocuments","tags":["ad-documents"],"parameters":[],"summary":"Dry-run an upload: every check, nothing written","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdDocumentUpload"}}}}}},"/api/v1/documents/upload":{"post":{"responses":{"201":{"description":"Written","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"documents":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"documentId":{"type":"string","format":"uuid"},"versionId":{"type":"string","format":"uuid"},"version":{"type":"string"},"changeClass":{"type":"string","enum":["ruling","conformance","editorial"]},"changeNote":{"type":"string"},"created":{"type":"boolean"}},"required":["code","documentId","versionId","version","changeClass","changeNote","created"]}},"decision":{"oneOf":[{"$ref":"#/components/schemas/AdDecision"},{"type":"null"}]}},"required":["documents","decision"]}},"required":["data"]}}}},"409":{"description":"VERSION_CONFLICT | PARKED_ITEMS_UNACKNOWLEDGED | DOCUMENT_ID_MISMATCH | DUPLICATE_IN_UPLOAD","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"DOCUMENT_INVALID | RULING_NEEDS_DECISION | DECISION_NEEDS_RULING | AMENDS_*","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"uploadAdDocuments","tags":["ad-documents"],"parameters":[],"summary":"Upload document versions (one transaction; lock-and-amend with a decision)","description":"Validates anatomy and citations, applies the version precondition and the parked gate, and records the change class. With a `decision` block every document is a ruling and the call is the lock-and-amend action.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdDocumentUpload"}}}}}},"/api/v1/documents/ratify":{"post":{"responses":{"201":{"description":"Ratified","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"decision":{"$ref":"#/components/schemas/AdDecision"},"documents":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"version":{"type":"string"},"versionId":{"type":"string","format":"uuid"}},"required":["code","version","versionId"]}},"domains":{"type":"array","items":{"$ref":"#/components/schemas/AdDomain"}}},"required":["decision","documents","domains"]}},"required":["data"]}}}},"404":{"description":"DOMAIN_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"DOMAIN_EMPTY | RATIFY_SET_MISMATCH | VERSION_CONFLICT | PARKED_ITEMS_UNACKNOWLEDGED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"ratifyAdDomains","tags":["ad-documents"],"parameters":[],"summary":"Bulk ratification: one decision locks v1.0 of every document in the domains","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"minItems":1,"maxItems":200},"documents":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","pattern":"^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*$"},"baseVersion":{"type":"string","pattern":"^\\d{1,4}(\\.\\d{1,4})?$"}},"required":["code","baseVersion"]},"minItems":1,"maxItems":2000},"decision":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"context":{"type":"string","minLength":1,"maxLength":50000},"options":{"type":"string","minLength":1,"maxLength":50000},"ruling":{"type":"string","minLength":1,"maxLength":50000},"consequences":{"type":"string","minLength":1,"maxLength":50000},"provenance":{"type":"string","minLength":1,"maxLength":50000}},"required":["title","context","options","ruling","consequences","provenance"]}},"required":["domains","documents","decision"]}}}}}},"/api/v1/documents/{code}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AdDocument"}},"required":["data"]}}}},"404":{"description":"DOCUMENT_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getAdDocument","tags":["ad-documents"],"parameters":[{"in":"path","name":"code","schema":{"type":"string","pattern":"^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*$"},"required":true}],"summary":"One document: current text, clauses, parked items and history"}},"/api/v1/documents/{code}/body":{"get":{"responses":{"200":{"description":"Markdown","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"DOCUMENT_NOT_FOUND | VERSION_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getAdDocumentBody","tags":["ad-documents"],"parameters":[{"in":"path","name":"code","schema":{"type":"string","pattern":"^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*$"},"required":true},{"in":"query","name":"version","schema":{"type":"string","pattern":"^\\d{1,4}(\\.\\d{1,4})?$"}}],"summary":"A document's text as markdown (current, or ?version=)"}},"/api/v1/documents/{code}/versions":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdDocumentVersionSummary"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}},"404":{"description":"DOCUMENT_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listAdDocumentVersions","tags":["ad-documents"],"parameters":[{"in":"path","name":"code","schema":{"type":"string","pattern":"^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*$"},"required":true}],"summary":"A document's version history, newest first"}},"/api/v1/documents/{code}/versions/{version}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AdDocumentVersion"}},"required":["data"]}}}},"404":{"description":"DOCUMENT_NOT_FOUND | VERSION_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getAdDocumentVersion","tags":["ad-documents"],"parameters":[{"in":"path","name":"code","schema":{"type":"string","pattern":"^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*$"},"required":true},{"in":"path","name":"version","schema":{"type":"string","pattern":"^\\d{1,4}(\\.\\d{1,4})?$"},"required":true}],"summary":"One version of a document, with its text"}},"/api/v1/documents/{code}/diff":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AdDocumentDiff"}},"required":["data"]}}}},"404":{"description":"DOCUMENT_NOT_FOUND | VERSION_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"diffAdDocumentVersions","tags":["ad-documents"],"parameters":[{"in":"path","name":"code","schema":{"type":"string","pattern":"^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*$"},"required":true},{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{1,4}(\\.\\d{1,4})?$"}},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{1,4}(\\.\\d{1,4})?$"}}],"summary":"Unified diff and clause changes between two versions"}},"/api/v1/documents/{code}/parked":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"code":{"type":"string"},"current":{"type":["object","null"],"properties":{"count":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"line":{"type":"integer"}},"required":["text","line"]}},"itemsSha256":{"type":["string","null"]},"acknowledgement":{"oneOf":[{"$ref":"#/components/schemas/ParkedAcknowledgement"},{"type":"null"}]}},"required":["count","items","itemsSha256","acknowledgement"]},"pending":{"type":"array","items":{"$ref":"#/components/schemas/ParkedAcknowledgement"}}},"required":["code","current","pending"]}},"required":["data"]}}}}},"operationId":"getAdDocumentParked","tags":["ad-documents"],"parameters":[{"in":"path","name":"code","schema":{"type":"string","pattern":"^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*$"},"required":true}],"summary":"A document's parked items and their acknowledgement"}},"/api/v1/documents/{code}/parked/acknowledge":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ParkedAcknowledgement"}},"required":["data"]}}}},"403":{"description":"OPERATOR_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"PARKED_LIST_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"acknowledgeAdDocumentParked","tags":["ad-documents"],"parameters":[{"in":"path","name":"code","schema":{"type":"string","pattern":"^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*$"},"required":true}],"summary":"The operator acknowledges a document's parked items (M05-11.2)","description":"Signed-in staff only, never an agent or an OAuth app.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"itemsSha256":{"type":"string","pattern":"^[0-9a-f]{64}$"}},"required":["itemsSha256"]}}}}}},"/api/v1/ad-decisions":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdDecisionListItem"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listAdDecisions","tags":["ad-decisions"],"parameters":[{"in":"query","name":"kind","schema":{"type":"string","enum":["ruling","ratification"]}},{"in":"query","name":"docCode","schema":{"type":"string","minLength":1,"maxLength":100}},{"in":"query","name":"q","schema":{"type":"string","minLength":1,"maxLength":200}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0}}],"summary":"List AD decisions, newest first"},"post":{"responses":{"201":{"description":"Locked","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"decision":{"$ref":"#/components/schemas/AdDecision"},"documents":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"documentId":{"type":"string","format":"uuid"},"versionId":{"type":"string","format":"uuid"},"version":{"type":"string"},"changeClass":{"type":"string","enum":["ruling","conformance","editorial"]},"changeNote":{"type":"string"},"created":{"type":"boolean"}},"required":["code","documentId","versionId","version","changeClass","changeNote","created"]}}},"required":["decision","documents"]}},"required":["data"]}}}},"409":{"description":"VERSION_CONFLICT | PARKED_ITEMS_UNACKNOWLEDGED | DOCUMENT_ID_MISMATCH","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"AMENDS_EMPTY | AMENDS_DOCUMENT_MISMATCH | AMENDS_CLAUSE_UNKNOWN | DOCUMENT_INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"lockAndAmendAdDecision","tags":["ad-decisions"],"parameters":[],"summary":"Lock-and-amend: mint DEC-nnnn and land every document version it names, atomically","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdLockAndAmend"}}}}}},"/api/v1/ad-decisions/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AdDecisionDetail"}},"required":["data"]}}}},"404":{"description":"DECISION_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getAdDecision","tags":["ad-decisions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^DEC-\\d{4,}$"},"required":true}],"summary":"One AD decision with its amends and the diffs it caused"}},"/api/v1/domains":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdDomain"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listAdDomains","tags":["ad-domains"],"parameters":[{"in":"query","name":"kind","schema":{"type":"string","enum":["rulebook-section","doctrine","service"]}},{"in":"query","name":"era","schema":{"type":"string","enum":["pre-dev","ad"]}}],"summary":"The domain ledger"}},"/api/v1/domains/{key}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/AdDomain"}],"properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/AdDocumentSummary"}}},"required":["documents"]}},"required":["data"]}}}},"404":{"description":"DOMAIN_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getAdDomain","tags":["ad-domains"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"key","required":true}],"summary":"One domain with its documents"}},"/api/v1/standardizations":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Standardization"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listStandardizations","tags":["standardizations"],"parameters":[{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["ratified","held","in_progress","done","wont_do"]},{"type":"array","items":{"type":"string","enum":["ratified","held","in_progress","done","wont_do"]}}]}},{"in":"query","name":"owner","schema":{"type":"string","minLength":1,"maxLength":200}},{"in":"query","name":"closes","schema":{"type":"string","minLength":1,"maxLength":100}}],"summary":"The STD items, as work"}},"/api/v1/standardizations/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Standardization"}},"required":["data"]}}}},"404":{"description":"STANDARDIZATION_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getStandardization","tags":["standardizations"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^STD-\\d{2,}$"},"required":true}],"summary":"One STD item"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Standardization"}},"required":["data"]}}}},"404":{"description":"STANDARDIZATION_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"ISSUE_NOT_FOUND | AD_DECISION_UNRESOLVED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateStandardization","tags":["standardizations"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^STD-\\d{2,}$"},"required":true}],"summary":"Track an STD item's work: status, issues, ratifying decision, note","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ratified","held","in_progress","done","wont_do"]},"issueKeys":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":200},"decisionId":{"type":["string","null"],"pattern":"^DEC-\\d{4,}$"},"progressNote":{"type":["string","null"],"maxLength":10000}}}}}}}},"/api/v1/archive":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ArchiveItem"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"searchPreDevArchive","tags":["archive"],"parameters":[{"in":"query","name":"kind","schema":{"anyOf":[{"type":"string","enum":["decision","doctrine","feature_doc","drift","request","open_question"]},{"type":"array","items":{"type":"string","enum":["decision","doctrine","feature_doc","drift","request","open_question"]}}]}},{"in":"query","name":"q","schema":{"type":"string","minLength":1,"maxLength":200}},{"in":"query","name":"serviceId","schema":{"type":"string","minLength":1,"maxLength":200}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0}}],"summary":"Browse and search the pre-dev archive"}},"/api/v1/archive/resolve":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ref":{"type":"string"},"kind":{"type":"string"},"resolvable":{"type":"boolean"},"found":{"type":"boolean"},"item":{"oneOf":[{"$ref":"#/components/schemas/ArchiveItem"},{"type":"null"}]},"clause":{"type":["string","null"]}},"required":["ref","kind","resolvable","found","item","clause"]}},"required":["data"]}}}},"400":{"description":"CITATION_INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"resolvePreCitation","tags":["archive"],"parameters":[{"in":"query","name":"ref","schema":{"type":"string","minLength":1,"maxLength":500},"required":true}],"summary":"Resolve one `pre:` citation to its archive row"}},"/api/v1/harness":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Harness"}},"required":["data"]}}}},"409":{"description":"METHODOLOGY_NOT_AVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"generateHarness","tags":["harness"],"parameters":[{"in":"query","name":"repo","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]*$"},"required":true},{"in":"query","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":false},{"in":"query","name":"includeDrafts","schema":{"type":"string","enum":["true","false"]},"required":false}],"summary":"Generate a repository's agent harness from the methodology"}},"/api/v1/harness/methodology":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"methodologyVersion":{"type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"version":{"type":"string"},"status":{"type":"string","enum":["draft","ratified"]}},"required":["code","title","version","status"]}}},"required":["methodologyVersion","sources"]}},"required":["data"]}}}},"409":{"description":"METHODOLOGY_NOT_AVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getHarnessMethodologyVersion","tags":["harness"],"parameters":[{"in":"query","name":"includeDrafts","schema":{"type":"string","enum":["true","false"]}}],"summary":"The current methodology version, for a cheap drift check"}},"/api/v1/services/{serviceId}/projects":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createProject","tags":["Projects"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","minLength":1},"required":true}],"summary":"Create a project (draft) — the bounded unit-of-implementation (D387)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"projectKey":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]*$","minLength":1},"title":{"type":"string","minLength":1},"summary":{"type":"string"},"planMd":{"type":"string"}},"required":["projectKey","title"]}}}}},"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceProjects","tags":["Projects"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","minLength":1},"required":true}],"summary":"List a service's projects"}},"/api/v1/projects/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getProject","tags":["Projects"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a project + its doctrine-coverage"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateProject","tags":["Projects"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update a project's title / summary / plan","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1},"summary":{"type":["string","null"]},"planMd":{"type":["string","null"]}}}}}}}},"/api/v1/projects/{id}/coverage":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProjectDoctrineCoverage"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"setProjectCoverage","tags":["Projects"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Set doctrine-coverage lines for a project (bulk upsert)","description":"One line per global doctrine (applicable: how / not-applicable: why). A project's scope can only be confirmed once every canonical global doctrine has a coverage line (D387).","requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"doctrineKey":{"type":"string","enum":["01-communication-doctrine","02-audit-doctrine","03-logging-doctrine","04-pii-doctrine","05-platform-tenant","06-library-integration","07-rbac-doctrine","08-rls-doctrine","09-replication-doctrine","10-approval-doctrine","11-dsar-doctrine","12-testing-doctrine","13-module-independence-doctrine","14-entity-authority-doctrine","15-telemetry-doctrine","16-obs-retention-and-backups-doctrine","17-infra-shape-doctrine","18-alerting-doctrine","19-self-monitoring-and-dr-doctrine","20-client-sdk-doctrine","21-oob-notification-delivery-doctrine","22-infra-obs-for-pane-doctrine"]},"applicability":{"type":"string","enum":["applicable","not-applicable"]},"note":{"type":"string","minLength":1}},"required":["doctrineKey","applicability","note"]},"minItems":1}}}}}},"/api/v1/projects/{id}/confirm-scope":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Scope incomplete / bad status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"confirmProjectScope","tags":["Projects"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Confirm scope (draft -> scope_confirmed) — GATED on full doctrine coverage","description":"Refuses with 422 PROJECT_SCOPE_INCOMPLETE + the missing doctrine list until every canonical global doctrine has a coverage line (D387)."}},"/api/v1/projects/{id}/transition":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"transitionProject","tags":["Projects"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Transition a project's status (implementing / verifying / complete / abandoned)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["implementing","verifying","complete","abandoned"]}},"required":["status"]}}}}}},"/api/v1/projects/{id}/findings":{"post":{"responses":{"200":{"description":"Routed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"routed":{"type":"number"},"notFound":{"type":"array","items":{"type":"string"}}},"required":["routed","notFound"]}},"required":["data"]}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"routeProjectFindings","tags":["Projects"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Route discovery findings (drift entries) into a project's scope","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"driftIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1}},"required":["driftIds"]}}}}}},"/api/v1/projects/{id}/findings/{driftId}":{"delete":{"responses":{"200":{"description":"Unrouted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"unrouted":{"type":"boolean","const":true}},"required":["unrouted"]}},"required":["data"]}}}},"404":{"description":"No such finding routed to this project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unrouteProjectFinding","tags":["Projects"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true},{"in":"path","name":"driftId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Un-route a finding from a project (clears its project_id)"}},"/api/v1/services/{serviceId}/slices":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Slice"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceSlices","tags":["Slices"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"List a service's implementation slices","description":"Returns every slice for the service, ordered by dagOrder then sliceKey."},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Slice"}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"(serviceId, sliceKey) already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createServiceSlice","tags":["Slices"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Create an implementation slice for a service","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sliceKey":{"type":"string","pattern":"^[a-z][a-z0-9-]*$"},"title":{"type":"string","minLength":1},"splitConcurrency":{"type":"integer","exclusiveMinimum":0},"dagOrder":{"type":"integer","minimum":0},"descriptionMd":{"type":"string","minLength":1}},"required":["sliceKey","title"]}}}}}},"/api/v1/slices/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Slice"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getSlice","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a slice by id"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Slice"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateSlice","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update a slice's mutable fields","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1},"splitConcurrency":{"type":"integer","exclusiveMinimum":0},"dagOrder":{"type":"integer","minimum":0},"status":{"type":"string","enum":["planned","locked","implementing","partially_implemented","implemented","deprecated"]},"completionPct":{"type":["integer","null"],"minimum":0,"maximum":100},"descriptionMd":{"type":"string","minLength":1}}}}}}}},"/api/v1/slices/{id}/lock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Slice"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Locked by another agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Owned minimums are not all locked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"lockSlice","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Lock a slice's minimum contract surface","description":"Sets lockedAt + lockedByAgentId. Gated on owned minimums: 422 SLICE_MINIMUMS_UNLOCKED (with the unlocked rows in details) when any owned slice_minimum is unlocked. Idempotent if already locked by the same agent; 409 LOCK_CONFLICT if locked by another agent."}},"/api/v1/slices/{id}/unlock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Slice"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unlockSlice","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Unlock a slice (operator escape hatch)","description":"Clears lockedAt + lockedByAgentId; rewinds locked → planned."}},"/api/v1/slices/{id}/implement":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Slice"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"implementSlice","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a slice implemented","description":"Sets status → implemented and completionPct → 100."}},"/api/v1/slices/{id}/claim":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Slice"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Lease held by another agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"claimSlice","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Acquire the slice work lease (CAS)","description":"Succeeds only when the lease is free, expired, or already held by the caller. Sets claimedByAgentId + claimExpiresAt = now + ttl (default 30 min). 409 SLICE_CLAIM_HELD on a lost race.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ttlMinutes":{"type":"integer","exclusiveMinimum":0,"maximum":1440}}}}}}}},"/api/v1/slices/{id}/release":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Slice"}},"required":["data"]}}}},"403":{"description":"Lease not held by this agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"releaseSlice","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Release the slice work lease","description":"Only the current holder (or an operator) may release. 403 if not the holder."}},"/api/v1/slices/{id}/feature-docs":{"post":{"responses":{"201":{"description":"Attached","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SliceFeatureDoc"}},"required":["data"]}}}},"404":{"description":"Slice or feature_doc not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"feature_doc belongs to a different service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"attachSliceFeatureDoc","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Attach a feature_doc to a slice (ownership)","description":"Records that the slice OWNS the feature_doc. Rejects 422 SLICE_FEATURE_DOC_SERVICE_MISMATCH when the feature_doc belongs to a different service. Idempotent on (sliceId, featureDocId).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"featureDocId":{"type":"string","format":"uuid"}},"required":["featureDocId"]}}}}},"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SliceFeatureDocEnriched"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listSliceFeatureDocs","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"List the feature_docs a slice owns"}},"/api/v1/slices/{id}/feature-docs/{featureDocId}":{"delete":{"responses":{"200":{"description":"Detached","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"detached":{"type":"boolean","const":true}},"required":["detached"]}},"required":["data"]}}}},"404":{"description":"No such ownership join","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"detachSliceFeatureDoc","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true},{"in":"path","name":"featureDocId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Detach a feature_doc from a slice"}},"/api/v1/slices/{id}/minimums":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SliceMinimum"}},"required":["data"]}}}},"404":{"description":"Slice not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"(sliceId, kind, name) already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createSliceMinimum","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Declare a minimum-shape seam on a slice","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["module_fn","module_type","internal_table_cols","constant","rest_surface","event_schema","cli_invocation"]},"name":{"type":"string","minLength":1},"signatureMd":{"type":"string","maxLength":2048},"shapeMd":{"type":"string","minLength":1}},"required":["kind","name"]}}}}},"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SliceMinimum"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listSliceMinimums","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"List a slice's minimums"}},"/api/v1/minimums/{id}/lock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SliceMinimum"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Locked by another agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"lockSliceMinimum","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Lock a minimum's shape (floor frozen)","description":"Idempotent if already locked by the same agent; 409 MINIMUM_LOCK_CONFLICT if locked by another agent."}},"/api/v1/minimums/{id}/unlock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SliceMinimum"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unlockSliceMinimum","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Unlock a minimum (operator escape hatch)"}},"/api/v1/minimums/{id}/implement":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SliceMinimum"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"implementSliceMinimum","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a minimum implemented"}},"/api/v1/slices/{id}/boundary-contracts":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SliceBoundaryContract"}},"required":["data"]}}}},"404":{"description":"Producer slice / referenced artifact / minimum not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Duplicate boundary contract","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Reference fields incomplete or invalid for refKind","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createSliceBoundaryContract","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Declare a cross-boundary contract from a producer slice","description":"refKind=artifact points at an existing Dev artifact row (validated to exist); refKind=minimum points at one of the slice's minimums. Deduped via NULLS NOT DISTINCT → 409 BOUNDARY_DUPLICATE on a repeat.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"consumerSliceId":{"type":"string","format":"uuid"},"consumerServiceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"refKind":{"type":"string","enum":["artifact","minimum"]},"artifactType":{"type":"string","enum":["grpc","rest","table","outbox","saga","sql"]},"artifactId":{"type":"string","format":"uuid"},"minimumId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["declared","locked","satisfied"]}},"required":["refKind"]}}}}},"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SliceBoundaryContract"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listSliceBoundaryContracts","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"List a producer slice's boundary contracts"}},"/api/v1/slices/{id}/deps":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SliceDep"}},"required":["data"]}}}},"404":{"description":"Slice or dependency target not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Edge already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Self-ref, cross-service, or cycle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"addSliceDep","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Add an intra-service dependency edge between slices","description":"Rejects self-references, cross-service deps, duplicates, and 422 SLICE_DEP_CYCLE when the edge would close a cycle (WITH RECURSIVE).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"dependsOnSliceId":{"type":"string","format":"uuid"}},"required":["dependsOnSliceId"]}}}}},"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SliceDep"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listSliceDeps","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"List a slice's dependency edges"}},"/api/v1/slices/{id}/recompute-status":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Slice"},"facts":{"type":"object","properties":{"sliceId":{"type":"string"},"featureDocsTotal":{"type":"integer"},"featureDocsImplemented":{"type":"integer"},"featureDocsPartiallyImplemented":{"type":"integer"},"featureDocsImplementing":{"type":"integer"},"completionPct":{"type":"integer"},"locked":{"type":"boolean"}},"required":["sliceId","featureDocsTotal","featureDocsImplemented","featureDocsPartiallyImplemented","featureDocsImplementing","completionPct","locked"]}},"required":["data","facts"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"recomputeSliceStatus","tags":["Slices"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Recompute a slice's status from its owned feature_docs","description":"Rolls up the slice's owned feature_docs into status + completionPct and returns both the updated row and the derivation facts."}},"/api/v1/services/{serviceId}/tables":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DbTable"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceTables","tags":["Tables"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true},{"in":"query","name":"preseeded","schema":{"type":"string","enum":["true","false"]}}],"summary":"List tables for a service","description":"Includes declaredIn when the repo-relative declaring file has been recorded."},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DbTable"}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Table name already exists for this service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createTable","tags":["Tables"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Add a table to a service","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"schemaText":{"type":"string","minLength":1},"description":{"type":["string","null"]},"declaredIn":{"type":["string","null"],"minLength":1,"maxLength":500},"preseeded":{"type":"boolean"}},"required":["name","schemaText"]}}}}}},"/api/v1/tables/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DbTable"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getTable","tags":["Tables"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a table by id"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DbTable"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateTable","tags":["Tables"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update schema text or description on a table","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"schemaText":{"type":"string","minLength":1},"description":{"type":["string","null"]},"declaredIn":{"type":["string","null"],"minLength":1,"maxLength":500}}}}}}},"delete":{"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"id":{"type":"string","format":"uuid"}},"required":["deleted","id"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Table is locked; pass ?force=true to delete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deleteTable","tags":["Tables"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true},{"in":"query","name":"force","schema":{"type":"string","enum":["true","false"]}}],"summary":"Delete a confirmed-dead/erroneous table row","description":"Hard-deletes the table row — for removing artifacts that no longer exist (dropped tables, erroneous entries). SAFETY GUARD: a locked table (lockedAt IS NOT NULL) is rejected with 409 unless ?force=true is passed, so live/locked contracts can't be accidentally deleted."}},"/api/v1/services/{serviceId}/tables/preseed":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"inserted":{"type":"integer","minimum":0},"skipped":{"type":"integer","minimum":0}},"required":["inserted","skipped"]}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"preseedTables","tags":["Tables"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Bulk preseed tables for a service (idempotent)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"schemaText":{"type":"string","minLength":1},"description":{"type":["string","null"]},"declaredIn":{"type":["string","null"],"minLength":1,"maxLength":500}},"required":["name","schemaText"]},"minItems":1}},"required":["tables"]}}}}}},"/api/v1/tables/{id}/implement":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DbTable"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"implementTable","tags":["Tables"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a table as implemented (shipped in real schema)","description":"Use after the producer service has shipped the table in its real migrations against the local stack per R1. Pairs with contract-lifecycle-progression skill."}},"/api/v1/tables/{id}/deprecate":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DbTable"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deprecateTable","tags":["Tables"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a table as deprecated","description":"Operator action when retiring a table. Replication consumers must migrate off."}},"/api/v1/tables/{id}/lock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DbTable"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"lockTable","tags":["Tables"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Lock a table's contract (freeze the minimum schema)","description":"Sets lockedAt/lockedByAgentId (+ optional lockedBySliceId). Orthogonal to status. Idempotent re-lock.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sliceId":{"type":"string","format":"uuid"}}}}}}}},"/api/v1/tables/{id}/unlock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DbTable"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unlockTable","tags":["Tables"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Unlock a table's contract (operator escape hatch)","description":"Clears lockedAt/lockedByAgentId/lockedBySliceId."}},"/api/v1/services/{serviceId}/sql-lookups":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SqlLookup"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceSqlLookups","tags":["SqlLookups"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["planned","implementing","implemented","deprecated"]},{"type":"array","items":{"type":"string","enum":["planned","implementing","implemented","deprecated"]}}]}}],"summary":"List SQL lookups for a service"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SqlLookup"}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"(serviceId, name) already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createSqlLookup","tags":["SqlLookups"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Add a SQL lookup for a service","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"},"signatureMd":{"type":["string","null"],"maxLength":2048},"bodyMd":{"type":"string"},"status":{"type":"string","enum":["planned","implementing","implemented","deprecated"]}},"required":["name"]}}}}}},"/api/v1/sql-lookups/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SqlLookup"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getSqlLookup","tags":["SqlLookups"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a SQL lookup by id (resolves the long-form body)"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SqlLookup"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateSqlLookup","tags":["SqlLookups"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update a SQL lookup (signature / body / status)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signatureMd":{"type":["string","null"],"maxLength":2048},"bodyMd":{"type":["string","null"]},"status":{"type":"string","enum":["planned","implementing","implemented","deprecated"]}}}}}}}},"/api/v1/sql-lookups/{id}/implement":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SqlLookup"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"implementSqlLookup","tags":["SqlLookups"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a SQL lookup as implemented (shipped in real schema)","description":"Use after the producer service has shipped + tested the optimized lookup against the real backing stack per R1. Pairs with contract-lifecycle-progression skill."}},"/api/v1/sql-lookups/{id}/lock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SqlLookup"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"lockSqlLookup","tags":["SqlLookups"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Lock a SQL lookup's contract (freeze the minimum)","description":"Sets lockedAt/lockedByAgentId (+ optional lockedBySliceId). Orthogonal to status. Idempotent re-lock.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sliceId":{"type":"string","format":"uuid"}}}}}}}},"/api/v1/sql-lookups/{id}/unlock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SqlLookup"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unlockSqlLookup","tags":["SqlLookups"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Unlock a SQL lookup's contract (operator escape hatch)","description":"Clears lockedAt/lockedByAgentId/lockedBySliceId."}},"/api/v1/services/{serviceId}/rest-interfaces":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RestInterfaceWithAliasTarget"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceRestInterfaces","tags":["RestInterfaces"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"List REST endpoints for a service","description":"Alias rows (kind='alias') resolve their target to a compact `aliasTarget` summary; standard rows carry `aliasTarget: null`."},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestInterfaceWithBehavior"}},"required":["data"]}}}},"400":{"description":"Alias-of-alias target (ALIAS_OF_ALIAS)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Service or alias target not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"(method, path) already exists for this service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createRestInterface","tags":["RestInterfaces"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Add a REST endpoint","description":"kind='alias' publishes a gateway re-exposure of another service's standard row (drift 0aa9d095 / D411): aliasTargetId is required, must reference an existing kind='standard' row (no alias-of-alias), and the alias inherits the target's request/response schemas (supplying its own is rejected).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]},"path":{"type":"string","pattern":"^\\/","minLength":1},"requestSchema":{},"responseSchema":{},"agentInvocable":{"type":"boolean"},"operationId":{"type":"string","minLength":1},"behaviorMd":{"type":"string"},"status":{"type":"string","enum":["planned","implemented","deprecated"]},"tier":{"type":"string","enum":["tenant-domain","platform-ops"]},"kind":{"type":"string","enum":["standard","alias"]},"aliasTargetId":{"type":"string","format":"uuid"}},"required":["method","path"]}}}}}},"/api/v1/rest-interfaces/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestInterfaceWithAliasTarget"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getRestInterface","tags":["RestInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a REST interface by id","description":"Alias rows (kind='alias') resolve their target to a compact `aliasTarget` summary; standard rows carry `aliasTarget: null`."},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestInterfaceWithBehavior"}},"required":["data"]}}}},"400":{"description":"Alias rule violation (ALIAS_SELF_REFERENCE / ALIAS_OF_ALIAS / ALIAS_TARGET_REQUIRED / ALIAS_TARGET_ON_STANDARD / ALIAS_SCHEMA_NOT_ALLOWED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found (row or alias target)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Standard row still targeted by aliases (ALIAS_HAS_DEPENDENTS)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateRestInterface","tags":["RestInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update a REST interface (schema / behavior / status / alias)","description":"Alias handling (drift 0aa9d095 / D411): `aliasTargetId` repoints an alias (target must exist, be kind='standard', and differ from the row itself); `kind` converts standard<->alias. Converting to standard auto-clears the pointer; converting to alias requires a target, drops own schemas, and is rejected while other aliases still point at the row.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]},"path":{"type":"string","pattern":"^\\/","minLength":1},"requestSchema":{},"responseSchema":{},"agentInvocable":{"type":"boolean"},"operationId":{"type":["string","null"],"minLength":1},"behaviorMd":{"type":["string","null"]},"status":{"type":"string","enum":["planned","implemented","deprecated"]},"tier":{"type":"string","enum":["tenant-domain","platform-ops"]},"kind":{"type":"string","enum":["standard","alias"]},"aliasTargetId":{"type":["string","null"],"format":"uuid"}}}}}}}},"/api/v1/rest-interfaces/{id}/implement":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestInterface"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"implementRestInterface","tags":["RestInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a REST interface as implemented","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"commitSha":{"type":"string","pattern":"^[0-9a-f]{7,40}$"}}}}}}}},"/api/v1/rest-interfaces/{id}/deprecate":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestInterface"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deprecateRestInterface","tags":["RestInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a REST interface as deprecated"}},"/api/v1/rest-interfaces/{id}/lock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestInterface"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"lockRestInterface","tags":["RestInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Lock a REST endpoint's contract (freeze the minimum)","description":"Sets lockedAt/lockedByAgentId (+ optional lockedBySliceId). Orthogonal to status. Idempotent re-lock.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sliceId":{"type":"string","format":"uuid"}}}}}}}},"/api/v1/rest-interfaces/{id}/unlock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestInterface"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unlockRestInterface","tags":["RestInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Unlock a REST endpoint's contract (operator escape hatch)","description":"Clears lockedAt/lockedByAgentId/lockedBySliceId."}},"/api/v1/grpc-interfaces":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GrpcInterface"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listGrpcInterfaces","tags":["GrpcInterfaces"],"parameters":[{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"agentInvocable","schema":{"type":"string","enum":["true","false"]}},{"in":"query","name":"sagaCallable","schema":{"type":"string","enum":["true","false"]}},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["planned","implemented","deprecated"]},{"type":"array","items":{"type":"string","enum":["planned","implemented","deprecated"]}}]}}],"summary":"Cross-service list of gRPC RPCs"}},"/api/v1/services/{serviceId}/grpc-interfaces":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GrpcInterface"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceGrpcInterfaces","tags":["GrpcInterfaces"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"List gRPC RPCs for a single service"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GrpcInterface"}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"(serviceId, grpcServiceName, rpcName) collides","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createGrpcInterface","tags":["GrpcInterfaces"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Add a gRPC RPC for a service","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"grpcServiceName":{"type":"string","minLength":1},"rpcName":{"type":"string","minLength":1},"requestProto":{"type":"string","minLength":1},"responseProto":{"type":"string","minLength":1},"agentInvocable":{"type":"boolean"},"sagaCallable":{"type":"boolean"},"operationId":{"type":"string","minLength":1},"requiredParams":{},"behaviorMd":{"type":"string"},"status":{"type":"string","enum":["planned","implemented","deprecated"]}},"required":["grpcServiceName","rpcName","requestProto","responseProto"]}}}}}},"/api/v1/grpc-interfaces/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GrpcInterface"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getGrpcInterface","tags":["GrpcInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a gRPC RPC by id"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GrpcInterface"},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateGrpcInterface","tags":["GrpcInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update a gRPC RPC (proto / behavior / flags)","description":"If requestProto or responseProto change AND downstream consumers exist, the response includes a warnings array but the patch is NOT rejected — the operator decides.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"grpcServiceName":{"type":"string","minLength":1},"rpcName":{"type":"string","minLength":1},"requestProto":{"type":"string","minLength":1},"responseProto":{"type":"string","minLength":1},"agentInvocable":{"type":"boolean"},"sagaCallable":{"type":"boolean"},"operationId":{"type":["string","null"],"minLength":1},"requiredParams":{},"behaviorMd":{"type":["string","null"]},"status":{"type":"string","enum":["planned","implemented","deprecated"]}}}}}}}},"/api/v1/grpc-interfaces/{id}/implement":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GrpcInterface"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"implementGrpcInterface","tags":["GrpcInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a gRPC RPC as implemented"}},"/api/v1/grpc-interfaces/{id}/deprecate":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GrpcInterface"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deprecateGrpcInterface","tags":["GrpcInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a gRPC RPC as deprecated"}},"/api/v1/grpc-interfaces/{id}/lock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GrpcInterface"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"lockGrpcInterface","tags":["GrpcInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Lock a gRPC RPC's contract (freeze the minimum for consumers)","description":"Sets lockedAt/lockedByAgentId (+ optional lockedBySliceId). Orthogonal to status — a contract can be locked while still 'planned'. Idempotent: re-locking by the same agent is a 200 no-op that preserves the original lock metadata.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sliceId":{"type":"string","format":"uuid"}}}}}}}},"/api/v1/grpc-interfaces/{id}/unlock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GrpcInterface"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unlockGrpcInterface","tags":["GrpcInterfaces"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Unlock a gRPC RPC's contract (operator escape hatch)","description":"Clears lockedAt/lockedByAgentId/lockedBySliceId."}},"/api/v1/outbox-topics":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OutboxTopic"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listOutboxTopics","tags":["Outbox"],"parameters":[{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"topicName","schema":{"type":"string"}},{"in":"query","name":"producerLocked","schema":{"type":"string","enum":["true","false"]}}],"summary":"Cross-service list of outbox topics"}},"/api/v1/services/{serviceId}/outbox-topics":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OutboxTopic"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceOutboxTopics","tags":["Outbox"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Outbox topics owned by a service"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OutboxTopic"}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Topic already exists for this service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createOutboxTopic","tags":["Outbox"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Add an outbox topic","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"topicName":{"type":"string","pattern":"^[a-z][a-z0-9_-]+(\\.[a-z0-9_-]+){2,3}\\.v\\d+$|^hr\\.statutory\\.[A-Z0-9]+(?:-(?:[A-Z0-9]+|[a-z][a-z0-9]*))*\\.[a-z0-9_-]+\\.v\\d+$"},"payloadSchema":{},"replicationStrategy":{"type":"string","enum":["bullmq","rpc","redis-streams"]},"description":{"type":["string","null"]},"producerLocked":{"type":"boolean"}},"required":["topicName"]}}}}}},"/api/v1/outbox-topics/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/OutboxTopic"}],"properties":{"consumers":{"type":"array","items":{"$ref":"#/components/schemas/OutboxConsumer"}}},"required":["consumers"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getOutboxTopic","tags":["Outbox"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a topic with embedded consumers"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OutboxTopic"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateOutboxTopic","tags":["Outbox"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update topic schema / strategy","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payloadSchema":{},"replicationStrategy":{"type":"string","enum":["bullmq","rpc","redis-streams"]},"description":{"type":["string","null"]},"producerLocked":{"type":"boolean"}}}}}}},"delete":{"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"id":{"type":"string","format":"uuid"}},"required":["deleted","id"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Topic is producer-locked; pass ?force=true to delete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deleteOutboxTopic","tags":["OutboxTopics"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true},{"in":"query","name":"force","schema":{"type":"string","enum":["true","false"]}}],"summary":"Delete a confirmed-dead/erroneous outbox topic","description":"Hard-deletes the topic row (consumers cascade; outbox service_edges are dropped in the same tx). For removing artifacts that no longer exist — phantom full-prefix topics, retired events. SAFETY GUARD: a producer-locked topic (producerLocked=true) is rejected with 409 unless ?force=true is passed, so live/locked contracts can't be accidentally deleted."}},"/api/v1/outbox-topics/{id}/consumers":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OutboxConsumer"}},"required":["data"]}}}},"404":{"description":"Topic or consumer service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Consumer already subscribed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"subscribeOutboxConsumer","tags":["Outbox"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Subscribe a service to an outbox topic","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"consumerServiceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"handlerDescription":{"type":["string","null"]}},"required":["consumerServiceId"]}}}}}},"/api/v1/outbox-topics/{id}/consumers/{consumerId}":{"delete":{"responses":{"204":{"description":"No content"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unsubscribeOutboxConsumer","tags":["Outbox"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true},{"in":"path","name":"consumerId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Remove a subscription"}},"/api/v1/outbox-topics/{id}/implement":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OutboxTopic"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"implementOutboxTopic","tags":["OutboxTopics"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Lock the outbox topic's producer (mark as implemented)","description":"Sets producerLocked=true. Use after the producer service has shipped the outbox emit code against the real backing stack per R1. Equivalent to a producer-locked-event signal — consumers can now wire against the topic and expect runtime success."}},"/api/v1/outbox-topics/{id}/unlock-producer":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OutboxTopic"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unlockOutboxTopicProducer","tags":["OutboxTopics"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Unlock the outbox topic's producer (revert to in-progress)","description":"Operator-only escape hatch: sets producerLocked=false. Used when a topic needs schema revision after locking. Consumers see this as 'the spec is mutable again'."}},"/api/v1/outbox-topics/{id}/lock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OutboxTopic"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"lockOutboxTopic","tags":["OutboxTopics"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Lock an outbox topic (set producerLocked + lockedAt atomically)","description":"Sets producerLocked=true AND lockedAt/lockedByAgentId (+ optional lockedBySliceId) in one UPDATE. `producerLocked` stays the authoritative gate signal; the lock columns carry uniform metadata. Idempotent re-lock preserves the original timestamp/agent/slice.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sliceId":{"type":"string","format":"uuid"}}}}}}}},"/api/v1/outbox-topics/{id}/unlock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OutboxTopic"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unlockOutboxTopic","tags":["OutboxTopics"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Unlock an outbox topic (clear producerLocked + lock columns)","description":"Clears producerLocked AND lockedAt/lockedByAgentId/lockedBySliceId atomically. Operator escape hatch."}},"/api/v1/approval-kinds":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApprovalKind"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}},"400":{"description":"Invalid filter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listApprovalKinds","tags":["ApprovalKinds"],"parameters":[{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["planned","implementing","implemented","deprecated"]},{"type":"array","items":{"type":"string","enum":["planned","implementing","implemented","deprecated"]}}]}},{"in":"query","name":"domain","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"venue","schema":{"anyOf":[{"type":"string","enum":["home","owning_module","either"]},{"type":"array","items":{"type":"string","enum":["home","owning_module","either"]}}]}},{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}],"summary":"Fleet-wide list of approval kinds (who approves what)","description":"Filter by domain, venue, status and serviceId (each repeatable). D924 §C cl. 13."}},"/api/v1/services/{serviceId}/approval-kinds":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApprovalKind"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}},"400":{"description":"Invalid filter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listServiceApprovalKinds","tags":["ApprovalKinds"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["planned","implementing","implemented","deprecated"]},{"type":"array","items":{"type":"string","enum":["planned","implementing","implemented","deprecated"]}}]}},{"in":"query","name":"domain","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"venue","schema":{"anyOf":[{"type":"string","enum":["home","owning_module","either"]},{"type":"array","items":{"type":"string","enum":["home","owning_module","either"]}}]}}],"summary":"Approval kinds declared by a service","description":"Filter by status, domain and venue (each repeatable)."},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApprovalKind"}},"required":["data"]}}}},"400":{"description":"Invalid declaration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The key is already declared for this service, or its namespace belongs to another service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The key's namespace is reserved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createApprovalKind","tags":["ApprovalKinds"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Declare an approval kind a service raises","description":"Declared `planned` (or `implementing`). The key's first segment is the declaring service's namespace: the first service to declare in a namespace owns it, and the five reserved module keys are refused. `defaultRoute` is the org-node walk (D924 §0); `outcomes` come from D240's vocabulary widened by D924 cl. 16.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*){2,3}$"},"label":{"type":"string","minLength":1},"domain":{"type":"string","pattern":"^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$"},"defaultRoute":{"$ref":"#/components/schemas/ApprovalKindDefaultRoute"},"maxLevels":{"type":["integer","null"],"minimum":1},"previewSchema":{"oneOf":[{"$ref":"#/components/schemas/ApprovalKindPreviewSchema"},{"type":"null"}]},"deferredAction":{"type":["string","null"],"minLength":1},"outcomes":{"type":"array","items":{"type":"string","enum":["approved","rejected","expired","changes_requested","approved_with_cuts"]},"minItems":1},"venue":{"type":"string","enum":["home","owning_module","either"]},"slaDefault":{"oneOf":[{"$ref":"#/components/schemas/ApprovalKindSla"},{"type":"null"}]},"onTimeoutDefault":{"type":["string","null"],"enum":["escalate_next","keep_open_remind_daily","lapse","none",null]},"permissionKey":{"type":"string","pattern":"^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*){2,3}$"},"entitlementKey":{"type":["string","null"],"pattern":"^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$"},"description":{"type":["string","null"]},"status":{"type":"string","enum":["planned","implementing"]}},"required":["key","label","domain","defaultRoute","outcomes","venue","permissionKey"],"additionalProperties":false}}}}}},"/api/v1/approval-kinds/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApprovalKind"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getApprovalKind","tags":["ApprovalKinds"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get an approval kind by id"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApprovalKind"}},"required":["data"]}}}},"400":{"description":"Invalid patch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Not editable in its status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateApprovalKind","tags":["ApprovalKinds"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Edit an approval kind while it is planned or implementing","description":"Any declared column except `key` and `status`. Refused with 409 APPROVAL_KIND_NOT_EDITABLE once the kind is implemented or deprecated.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1},"domain":{"type":"string","pattern":"^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$"},"defaultRoute":{"$ref":"#/components/schemas/ApprovalKindDefaultRoute"},"maxLevels":{"type":["integer","null"],"minimum":1},"previewSchema":{"oneOf":[{"$ref":"#/components/schemas/ApprovalKindPreviewSchema"},{"type":"null"}]},"deferredAction":{"type":["string","null"],"minLength":1},"outcomes":{"type":"array","items":{"type":"string","enum":["approved","rejected","expired","changes_requested","approved_with_cuts"]},"minItems":1},"venue":{"type":"string","enum":["home","owning_module","either"]},"slaDefault":{"oneOf":[{"$ref":"#/components/schemas/ApprovalKindSla"},{"type":"null"}]},"onTimeoutDefault":{"type":["string","null"],"enum":["escalate_next","keep_open_remind_daily","lapse","none",null]},"permissionKey":{"type":"string","pattern":"^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*){2,3}$"},"entitlementKey":{"type":["string","null"],"pattern":"^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$"},"description":{"type":["string","null"]}},"additionalProperties":false}}}}}},"/api/v1/approval-kinds/{id}/mark-implementing":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApprovalKind"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Refused transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"markApprovalKindImplementing","tags":["ApprovalKinds"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"planned → implementing (the producer started building it)","description":"contract-lifecycle-progression. Idempotent on an implementing kind; 409 from implemented or deprecated."}},"/api/v1/approval-kinds/{id}/implement":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApprovalKind"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Refused transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"implementApprovalKind","tags":["ApprovalKinds"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark an approval kind implemented (verified on the real stack)","description":"planned | implementing → implemented, after the raising service proved a real chain end to end (R1). Idempotent; 409 from deprecated."}},"/api/v1/approval-kinds/{id}/deprecate":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApprovalKind"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Refused transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deprecateApprovalKind","tags":["ApprovalKinds"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Deprecate an approval kind (terminal)","description":"Any status → deprecated. Idempotent. Nothing moves a kind out of deprecated."}},"/api/v1/approval-kinds/{id}/lock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApprovalKind"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"lockApprovalKind","tags":["ApprovalKinds"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Lock an approval kind's contract (freeze the declaration)","description":"Sets lockedAt/lockedByAgentId (+ optional lockedBySliceId). Orthogonal to status. Idempotent re-lock keeps the original metadata.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sliceId":{"type":"string","format":"uuid"}}}}}}}},"/api/v1/approval-kinds/{id}/unlock":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApprovalKind"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"unlockApprovalKind","tags":["ApprovalKinds"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Unlock an approval kind's contract (operator escape hatch)","description":"Clears lockedAt/lockedByAgentId/lockedBySliceId."}},"/api/v1/libraries":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Library"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listLibraries","tags":["Libraries"],"parameters":[],"summary":"List libraries"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Library"}},"required":["data"]}}}},"409":{"description":"Library name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createLibrary","tags":["Libraries"],"parameters":[],"summary":"Create a library record","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"repoUrl":{"type":["string","null"],"format":"uri"},"version":{"type":"string"},"status":{"type":"string","enum":["planned","active","deprecated"]},"description":{"type":["string","null"]}},"required":["name"]}}}}}},"/api/v1/libraries/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Library"}],"properties":{"consumers":{"type":"array","items":{"$ref":"#/components/schemas/ServiceLibraryDep"}}},"required":["consumers"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getLibrary","tags":["Libraries"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a library with its consumers"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Library"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateLibrary","tags":["Libraries"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update version / status / repo","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"repoUrl":{"type":["string","null"],"format":"uri"},"version":{"type":"string"},"status":{"type":"string","enum":["planned","active","deprecated"]},"description":{"type":["string","null"]}}}}}}}},"/api/v1/libraries/{id}/versions":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LibraryVersion"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}},"404":{"description":"Library not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listLibraryVersions","tags":["Libraries"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"List published versions for a library"},"post":{"responses":{"200":{"description":"OK (upserted)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LibraryVersion"}},"required":["data"]}}}},"404":{"description":"Library not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"registerLibraryVersion","tags":["Libraries"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Register a published version for a library","description":"Upserts a version record for the library and syncs `libraries.version` to the registered version. Called by the operator or a libs agent after publishing to npm/pypi/go. Use the `capabilities` field (comma-separated API surface) instead of version strings for capability gates.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","minLength":1},"capabilities":{"type":["string","null"]},"commitSha":{"type":["string","null"]},"publishedAt":{"type":"string","format":"date-time"},"releaseNotes":{"type":["string","null"]}},"required":["version"]}}}}}},"/api/v1/services/{serviceId}/library-deps":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/ServiceLibraryDep"}],"properties":{"library":{"oneOf":[{"$ref":"#/components/schemas/Library"},{"type":"null"}]}},"required":["library"]}},"total":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceLibraryDeps","tags":["Libraries"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"List library deps for a service"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ServiceLibraryDep"}},"required":["data"]}}}},"404":{"description":"Service or library not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Dep already exists — use PATCH instead","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"addLibraryDep","tags":["Libraries"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Add a library dep to a service","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"libraryId":{"type":"string","format":"uuid"},"versionConstraint":{"type":"string","minLength":1}},"required":["libraryId","versionConstraint"]}}}}}},"/api/v1/services/{serviceId}/library-deps/{libId}":{"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ServiceLibraryDep"}},"required":["data"]}}}},"404":{"description":"Dep not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateLibraryDep","tags":["Libraries"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true},{"in":"path","name":"libId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update version constraint","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"versionConstraint":{"type":"string","minLength":1}},"required":["versionConstraint"]}}}}},"delete":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"removed":{"type":"string"}},"required":["removed"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"removeLibraryDep","tags":["Libraries"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true},{"in":"path","name":"libId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Remove a library dep"}},"/api/v1/service-edges":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ServiceEdge"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceEdges","tags":["ServiceEdges"],"parameters":[{"in":"query","name":"from","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"to","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"kind","schema":{"anyOf":[{"type":"string","enum":["grpc","rest","outbox","saga"]},{"type":"array","items":{"type":"string","enum":["grpc","rest","outbox","saga"]}}]}},{"in":"query","name":"status","schema":{"type":"string","enum":["planned","implemented","deprecated"]}}],"summary":"List service edges with filters"}},"/api/v1/services/{serviceId}/edges":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"in":{"type":"array","items":{"$ref":"#/components/schemas/ServiceEdge"}},"out":{"type":"array","items":{"$ref":"#/components/schemas/ServiceEdge"}}},"required":["in","out"]}},"required":["data"]}}}}},"operationId":"getServiceEdgesForService","tags":["ServiceEdges"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true},{"in":"query","name":"direction","schema":{"type":"string","enum":["in","out","both"]}}],"summary":"Edges in/out of a single service"}},"/api/v1/changelog":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChangelogEntry"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listChangelog","tags":["Changelog"],"parameters":[{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"requestHash","schema":{"type":"string","pattern":"^[0-9a-f]{16}$"}},{"in":"query","name":"since","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"until","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"affects","schema":{"type":"string","pattern":"^[a-z_]+:.+$"}},{"in":"query","name":"limit","schema":{"type":"string","pattern":"^\\d+$"}},{"in":"query","name":"offset","schema":{"type":"string","pattern":"^\\d+$"}}],"summary":"List changelog entries with filters"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChangelogEntry"}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"appendChangelog","tags":["Changelog"],"parameters":[],"summary":"Append a changelog entry","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"serviceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"commitSha":{"type":"string","pattern":"^[0-9a-f]{7,40}$"},"summary":{"type":"string","minLength":1},"bodyMd":{"type":["string","null"]},"prUrl":{"type":["string","null"],"format":"uri"},"requestHash":{"type":["string","null"],"pattern":"^[0-9a-f]{16}$"},"affectedArtifacts":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["feature_doc","table","rest_interface","grpc_interface","saga","saga_step","outbox_topic","outbox_consumer","decision","library","library_dep"]},"id":{"type":"string"},"action":{"type":"string","enum":["created","updated","deprecated","deleted","implemented"]}},"required":["kind","id","action"]}}},"required":["serviceId","commitSha","summary"]}}}}}},"/api/v1/services/{serviceId}/changelog":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChangelogEntry"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceChangelog","tags":["Changelog"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true},{"in":"query","name":"requestHash","schema":{"type":"string","pattern":"^[0-9a-f]{16}$"}},{"in":"query","name":"since","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"until","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"affects","schema":{"type":"string","pattern":"^[a-z_]+:.+$"}},{"in":"query","name":"limit","schema":{"type":"string","pattern":"^\\d+$"}},{"in":"query","name":"offset","schema":{"type":"string","pattern":"^\\d+$"}}],"summary":"Changelog entries for a service"}},"/api/v1/changelog/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChangelogEntry"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getChangelogEntry","tags":["Changelog"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a changelog entry by id"}},"/api/v1/health-verdicts":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HealthVerdict"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listHealthVerdicts","tags":["HealthVerdicts"],"parameters":[],"summary":"Latest verdict per service"}},"/api/v1/services/{serviceId}/health-verdicts":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HealthVerdict"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceHealthVerdicts","tags":["HealthVerdicts"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Verdict history for a service"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HealthVerdict"}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postHealthVerdict","tags":["HealthVerdicts"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Post a new verdict for a service","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"verdict":{"type":"string","enum":["good","degraded","bad"]},"reasons":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"artifactType":{"type":"string"},"artifactId":{"type":"string"}},"required":["code","message"]}},"evaluator":{"type":"string","minLength":1}},"required":["verdict","evaluator"]}}}}}},"/api/v1/services/{serviceId}/health":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HealthVerdict"}},"required":["data"]}}}},"404":{"description":"No verdict ever posted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getServiceHealth","tags":["HealthVerdicts"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Latest verdict for a single service"}},"/api/v1/drift":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DriftEntry"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listDrift","tags":["Drift"],"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":500}},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0}},{"in":"query","name":"severity","schema":{"anyOf":[{"type":"string","enum":["local","consumer-visible","breaking"]},{"type":"array","items":{"type":"string","enum":["local","consumer-visible","breaking"]}}]}},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["open","accepted-as-canonical","operator-resolved","superseded"]},{"type":"array","items":{"type":"string","enum":["open","accepted-as-canonical","operator-resolved","superseded"]}}]}},{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"since","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"since_days","schema":{"type":"string","pattern":"^\\d+$"}}],"summary":"Cross-service drift list with filters"}},"/api/v1/services/{serviceId}/drift":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DriftEntry"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceDrift","tags":["Drift"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Drift log for a single service"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DriftEntry"}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"fileDrift","tags":["Drift"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"File a new drift entry","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"severity":{"type":"string","enum":["local","consumer-visible","breaking"]},"summary":{"type":"string","minLength":1},"bodyMd":{"type":"string","minLength":1},"relatedArtifactType":{"type":["string","null"]},"relatedArtifactId":{"type":["string","null"]},"projectId":{"type":["string","null"],"format":"uuid"}},"required":["severity","summary","bodyMd"]}}}}}},"/api/v1/drift/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DriftEntry"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getDrift","tags":["Drift"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a drift entry by id"}},"/api/v1/drift/{id}/accept":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DriftEntry"}},"required":["data"]}}}},"404":{"description":"Drift or decision not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Invalid transition (not in 'open' status)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"acceptDrift","tags":["Drift"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Accept drift as canonical (requires a relatedDecisionId)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"relatedDecisionId":{"type":"string","pattern":"^(D\\d+|DEC-\\d{4,})$"},"resolutionMd":{"type":["string","null"]}},"required":["relatedDecisionId"]}}}}}},"/api/v1/drift/{id}/operator-resolve":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DriftEntry"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Invalid transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"operatorResolveDrift","tags":["Drift"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark drift as operator-resolved","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"resolutionMd":{"type":"string","minLength":1}},"required":["resolutionMd"]}}}}}},"/api/v1/drift/{id}/supersede":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DriftEntry"}},"required":["data"]}}}},"404":{"description":"Drift or superseding drift not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Invalid transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"supersedeDrift","tags":["Drift"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark drift as superseded by another drift entry","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"supersedingDriftId":{"type":"string","format":"uuid"},"resolutionMd":{"type":["string","null"]}},"required":["supersedingDriftId"]}}}}}},"/api/v1/pipelines":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Pipeline"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listPipelines","tags":["Pipelines"],"parameters":[{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"kind","schema":{"anyOf":[{"type":"string","enum":["rpc_mutator","rpc_query","http_webhook","worker_cron","worker_lease"]},{"type":"array","items":{"type":"string","enum":["rpc_mutator","rpc_query","http_webhook","worker_cron","worker_lease"]}}]}},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["planned","implemented","deprecated"]},{"type":"array","items":{"type":"string","enum":["planned","implemented","deprecated"]}}]}},{"in":"query","name":"sagaId","schema":{"type":"string","format":"uuid"}}],"summary":"List pipelines (filter by service, kind, status, saga)"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Pipeline"}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"(serviceId, name) already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Required H1 sections missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createPipeline","tags":["Pipelines"],"parameters":[],"summary":"Create a pipeline","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"serviceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"name":{"type":"string","pattern":"^[a-z][a-z0-9-]*$"},"kind":{"type":"string","enum":["rpc_mutator","rpc_query","http_webhook","worker_cron","worker_lease"]},"trigger":{"type":"string","minLength":1},"grpcInterfaceId":{"type":["string","null"],"format":"uuid"},"restInterfaceId":{"type":["string","null"],"format":"uuid"},"sagaId":{"type":["string","null"],"format":"uuid"},"sagaStepOrder":{"type":["integer","null"],"exclusiveMinimum":0},"bodyMd":{"type":"string","minLength":1},"status":{"type":"string","enum":["planned","implemented","deprecated"]}},"required":["serviceId","name","kind","trigger","bodyMd"]}}}}}},"/api/v1/pipelines/by-key/{serviceId}/{name}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Pipeline"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getPipelineByKey","tags":["Pipelines"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true},{"in":"path","name":"name","schema":{"type":"string","pattern":"^[a-z][a-z0-9-]*$"},"required":true}],"summary":"Get a pipeline by (serviceId, name); body inlined"}},"/api/v1/services/{serviceId}/pipelines":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Pipeline"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServicePipelines","tags":["Pipelines"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"List pipelines for a service"}},"/api/v1/pipelines/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Pipeline"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getPipeline","tags":["Pipelines"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a pipeline by id; body inlined from S3"},"put":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Pipeline"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Required H1 sections missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"replacePipeline","tags":["Pipelines"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Replace a pipeline (full body update)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["rpc_mutator","rpc_query","http_webhook","worker_cron","worker_lease"]},"trigger":{"type":"string","minLength":1},"grpcInterfaceId":{"type":["string","null"],"format":"uuid"},"restInterfaceId":{"type":["string","null"],"format":"uuid"},"sagaId":{"type":["string","null"],"format":"uuid"},"sagaStepOrder":{"type":["integer","null"],"exclusiveMinimum":0},"bodyMd":{"type":"string","minLength":1},"status":{"type":"string","enum":["planned","implemented","deprecated"]}}}}}}},"delete":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Pipeline"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deprecatePipeline","tags":["Pipelines"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Soft-delete (status=deprecated)"}},"/api/v1/doctrine-exceptions":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DoctrineException"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listDoctrineExceptions","tags":["DoctrineExceptions"],"parameters":[{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["active","sunset_planned","revoked"]},{"type":"array","items":{"type":"string","enum":["active","sunset_planned","revoked"]}}]}},{"in":"query","name":"doctrinePath","schema":{"type":"string"}},{"in":"query","name":"decisionId","schema":{"type":"string","pattern":"^([a-z][a-z0-9_-]*-)?D\\d+$"}}],"summary":"List doctrine exceptions"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DoctrineException"}},"required":["data"]}}}},"404":{"description":"Service or doctrine not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Exception already exists for this (service, path, scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Rationale missing required H1 sections, or decision not locked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"fileDoctrineException","tags":["DoctrineExceptions"],"parameters":[],"summary":"File a new doctrine exception","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"serviceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"doctrinePath":{"type":"string","minLength":1},"scope":{"type":"string","minLength":1},"rationaleMd":{"type":"string","minLength":1},"decisionId":{"type":["string","null"],"pattern":"^([a-z][a-z0-9_-]*-)?D\\d+$"},"sunsetTargetDate":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["serviceId","doctrinePath","scope","rationaleMd"]}}}}}},"/api/v1/services/{serviceId}/doctrine-exceptions":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DoctrineException"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceDoctrineExceptions","tags":["DoctrineExceptions"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"All doctrine exceptions for a service"}},"/api/v1/doctrine-exceptions/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DoctrineException"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getDoctrineException","tags":["DoctrineExceptions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a doctrine exception by id; rationale inlined"},"put":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DoctrineException"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Rationale sections missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateDoctrineException","tags":["DoctrineExceptions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update rationale / scope / status","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","minLength":1},"rationaleMd":{"type":"string","minLength":1},"decisionId":{"type":["string","null"],"pattern":"^([a-z][a-z0-9_-]*-)?D\\d+$"},"status":{"type":"string","enum":["active","sunset_planned","revoked"]},"sunsetTargetDate":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}}}}}}},"/api/v1/doctrine-exceptions/{id}/revoke":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DoctrineException"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"revokeDoctrineException","tags":["DoctrineExceptions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Revoke (status → revoked)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"revocationReason":{"type":"string","minLength":1}},"required":["revocationReason"]}}}}}},"/api/v1/doctrine-exceptions/{id}/plan-sunset":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DoctrineException"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"planDoctrineExceptionSunset","tags":["DoctrineExceptions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Plan sunset (status → sunset_planned)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sunsetTargetDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["sunsetTargetDate"]}}}}}},"/api/v1/doctrine/{path}/exceptions":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DoctrineException"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listExceptionsForDoctrinePath","tags":["DoctrineExceptions"],"parameters":[{"in":"path","name":"path","schema":{"type":"string","minLength":1},"required":true}],"summary":"All services diverging from a doctrine path"}},"/api/v1/runbooks":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Runbook"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listRunbooks","tags":["Runbooks"],"parameters":[{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"kind","schema":{"anyOf":[{"type":"string","enum":["local_dev","operations","incident","key_management","compliance","release"]},{"type":"array","items":{"type":"string","enum":["local_dev","operations","incident","key_management","compliance","release"]}}]}},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["active","stale","superseded"]},{"type":"array","items":{"type":"string","enum":["active","stale","superseded"]}}]}}],"summary":"List runbooks"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Runbook"}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"(serviceId, repoRelativePath) already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Required H1 sections missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"registerRunbook","tags":["Runbooks"],"parameters":[],"summary":"Register a runbook","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"serviceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"title":{"type":"string","minLength":1},"kind":{"type":"string","enum":["local_dev","operations","incident","key_management","compliance","release"]},"repoRelativePath":{"type":"string","minLength":1},"summaryMd":{"type":"string","minLength":1}},"required":["serviceId","title","kind","repoRelativePath","summaryMd"]}}}}}},"/api/v1/services/{serviceId}/runbooks":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Runbook"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceRunbooks","tags":["Runbooks"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"All runbooks for a service"}},"/api/v1/runbooks/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Runbook"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getRunbook","tags":["Runbooks"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a runbook; summary inlined"},"put":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Runbook"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Summary missing required H1 sections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateRunbook","tags":["Runbooks"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update a runbook","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1},"kind":{"type":"string","enum":["local_dev","operations","incident","key_management","compliance","release"]},"repoRelativePath":{"type":"string","minLength":1},"summaryMd":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","stale","superseded"]}}}}}}}},"/api/v1/runbooks/{id}/verify":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Runbook"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"verifyRunbook","tags":["Runbooks"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Stamp lastVerifiedAt = now()"}},"/api/v1/runbooks/{id}/mark-stale":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Runbook"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"markRunbookStale","tags":["Runbooks"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a runbook stale","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1}},"required":["reason"]}}}}}},"/api/v1/runbooks/{id}/supersede":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Runbook"}},"required":["data"]}}}},"404":{"description":"Source or replacement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"supersedeRunbook","tags":["Runbooks"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a runbook superseded and link the replacement","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"supersededById":{"type":"string","format":"uuid"}},"required":["supersededById"]}}}}}},"/api/v1/open-questions":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OpenQuestion"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listOpenQuestions","tags":["OpenQuestions"],"parameters":[{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"module","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["open","in_discussion","answered","obsolete"]},{"type":"array","items":{"type":"string","enum":["open","in_discussion","answered","obsolete"]}}]}},{"in":"query","name":"priority","schema":{"anyOf":[{"type":"string","enum":["low","medium","high","blocker"]},{"type":"array","items":{"type":"string","enum":["low","medium","high","blocker"]}}]}},{"in":"query","name":"topicTag","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}],"summary":"List open questions"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OpenQuestion"}},"required":["data"]}}}},"404":{"description":"Service not found (if serviceId set)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Scope required, or context missing required sections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"raiseOpenQuestion","tags":["OpenQuestions"],"parameters":[],"summary":"Raise a new open question","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"serviceId":{"type":["string","null"],"pattern":"^[a-z][a-z0-9_-]*$"},"module":{"type":["string","null"],"minLength":1},"questionMd":{"type":"string","minLength":1},"contextMd":{"type":"string","minLength":1},"topicTags":{"type":"array","items":{"type":"string"},"default":[]},"priority":{"type":"string","enum":["low","medium","high","blocker"],"default":"medium"}},"required":["questionMd"]}}}}}},"/api/v1/services/{serviceId}/open-questions":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OpenQuestion"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listServiceOpenQuestions","tags":["OpenQuestions"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"All open questions for a service"}},"/api/v1/open-questions/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OpenQuestion"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getOpenQuestion","tags":["OpenQuestions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get an open question; context inlined when present"},"put":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OpenQuestion"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Context missing required H1 sections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateOpenQuestion","tags":["OpenQuestions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update question / context / metadata","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"questionMd":{"type":"string","minLength":1},"contextMd":{"type":"string","minLength":1},"topicTags":{"type":"array","items":{"type":"string"}},"priority":{"type":"string","enum":["low","medium","high","blocker"]},"status":{"type":"string","enum":["open","in_discussion","obsolete"]}}}}}}}},"/api/v1/open-questions/{id}/answer":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OpenQuestion"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Already answered, or decision not locked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"answerOpenQuestion","tags":["OpenQuestions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Answer by linking to a locked decision","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"decisionId":{"type":"string","pattern":"^(([a-z][a-z0-9_-]*-)?D\\d+|DEC-\\d{4,})$"},"resolutionSummary":{"type":"string"}},"required":["decisionId"]}}}}}},"/api/v1/open-questions/{id}/mark-obsolete":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OpenQuestion"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"markOpenQuestionObsolete","tags":["OpenQuestions"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark obsolete (question no longer applies)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1}},"required":["reason"]}}}}}},"/api/v1/skills":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"version":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"name":{"type":"string"},"description":{"type":"string"},"allowedTools":{"type":["string","null"]},"scope":{"type":"string","enum":["global","project"]},"status":{"type":"string","enum":["active","deprecated","superseded"]},"bodyS3Key":{"type":"string"},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"repoUrl":{"type":["string","null"]},"supersedesId":{"type":["string","null"],"format":"uuid"},"projectSlug":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","slug","version","name","description","allowedTools","scope","status","bodyS3Key","bodySha256","bodyBytes","repoUrl","supersedesId","projectSlug","createdByAgentId","createdAt","updatedAt"]}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listSkills","tags":["Skills"],"parameters":[{"in":"query","name":"scope","schema":{"type":"string","enum":["global","project"]}},{"in":"query","name":"status","schema":{"type":"string","enum":["active","deprecated","superseded"]}},{"in":"query","name":"projectSlug","schema":{"type":"string"}}],"summary":"List skills"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"version":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"name":{"type":"string"},"description":{"type":"string"},"allowedTools":{"type":["string","null"]},"scope":{"type":"string","enum":["global","project"]},"status":{"type":"string","enum":["active","deprecated","superseded"]},"bodyS3Key":{"type":"string"},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"repoUrl":{"type":["string","null"]},"supersedesId":{"type":["string","null"],"format":"uuid"},"projectSlug":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","slug","version","name","description","allowedTools","scope","status","bodyS3Key","bodySha256","bodyBytes","repoUrl","supersedesId","projectSlug","createdByAgentId","createdAt","updatedAt"]}},"required":["data"]}}}},"409":{"description":"Slug already has an active version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createSkill","tags":["Skills"],"parameters":[],"summary":"Register a new skill (v1)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z][a-z0-9-]*$","minLength":2},"name":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"allowedTools":{"type":["string","null"]},"scope":{"type":"string","enum":["global","project"]},"projectSlug":{"type":["string","null"]},"repoUrl":{"type":["string","null"],"format":"uri"},"bodyMd":{"type":"string","minLength":1}},"required":["slug","name","description","bodyMd"]}}}}}},"/api/v1/skills/slugs":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}}},"required":["data"]}}}}},"operationId":"listSkillSlugs","tags":["Skills"],"parameters":[],"summary":"List active skill slugs (lightweight bootstrap check)"}},"/api/v1/skills/by-slug/{slug}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"version":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"name":{"type":"string"},"description":{"type":"string"},"allowedTools":{"type":["string","null"]},"scope":{"type":"string","enum":["global","project"]},"status":{"type":"string","enum":["active","deprecated","superseded"]},"bodyS3Key":{"type":"string"},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"repoUrl":{"type":["string","null"]},"supersedesId":{"type":["string","null"],"format":"uuid"},"projectSlug":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","slug","version","name","description","allowedTools","scope","status","bodyS3Key","bodySha256","bodyBytes","repoUrl","supersedesId","projectSlug","createdByAgentId","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getSkillBySlug","tags":["Skills"],"parameters":[{"in":"path","name":"slug","schema":{"type":"string","minLength":1},"required":true}],"summary":"Get latest active version of a skill by slug"}},"/api/v1/skills/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"version":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"name":{"type":"string"},"description":{"type":"string"},"allowedTools":{"type":["string","null"]},"scope":{"type":"string","enum":["global","project"]},"status":{"type":"string","enum":["active","deprecated","superseded"]},"bodyS3Key":{"type":"string"},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"repoUrl":{"type":["string","null"]},"supersedesId":{"type":["string","null"],"format":"uuid"},"projectSlug":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","slug","version","name","description","allowedTools","scope","status","bodyS3Key","bodySha256","bodyBytes","repoUrl","supersedesId","projectSlug","createdByAgentId","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getSkillById","tags":["Skills"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a skill by UUID"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"version":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"name":{"type":"string"},"description":{"type":"string"},"allowedTools":{"type":["string","null"]},"scope":{"type":"string","enum":["global","project"]},"status":{"type":"string","enum":["active","deprecated","superseded"]},"bodyS3Key":{"type":"string"},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"repoUrl":{"type":["string","null"]},"supersedesId":{"type":["string","null"],"format":"uuid"},"projectSlug":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","slug","version","name","description","allowedTools","scope","status","bodyS3Key","bodySha256","bodyBytes","repoUrl","supersedesId","projectSlug","createdByAgentId","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"patchSkillMeta","tags":["Skills"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update skill metadata without creating a new body revision","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"repoUrl":{"type":["string","null"],"format":"uri"}}}}}}}},"/api/v1/skills/{id}/body":{"get":{"responses":{"200":{"description":"Markdown body","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getSkillBody","tags":["Skills"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Download skill body markdown from S3"}},"/api/v1/skills/{id}/revise":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"version":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"name":{"type":"string"},"description":{"type":"string"},"allowedTools":{"type":["string","null"]},"scope":{"type":"string","enum":["global","project"]},"status":{"type":"string","enum":["active","deprecated","superseded"]},"bodyS3Key":{"type":"string"},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"repoUrl":{"type":["string","null"]},"supersedesId":{"type":["string","null"],"format":"uuid"},"projectSlug":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","slug","version","name","description","allowedTools","scope","status","bodyS3Key","bodySha256","bodyBytes","repoUrl","supersedesId","projectSlug","createdByAgentId","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Skill not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"reviseSkill","tags":["Skills"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Create a new version of a skill","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"allowedTools":{"type":["string","null"]},"repoUrl":{"type":["string","null"],"format":"uri"},"bodyMd":{"type":"string","minLength":1}},"required":["bodyMd"]}}}}}},"/api/v1/skills/{id}/deprecate":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"version":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"name":{"type":"string"},"description":{"type":"string"},"allowedTools":{"type":["string","null"]},"scope":{"type":"string","enum":["global","project"]},"status":{"type":"string","enum":["active","deprecated","superseded"]},"bodyS3Key":{"type":"string"},"bodySha256":{"type":"string"},"bodyBytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"repoUrl":{"type":["string","null"]},"supersedesId":{"type":["string","null"],"format":"uuid"},"projectSlug":{"type":["string","null"]},"createdByAgentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","slug","version","name","description","allowedTools","scope","status","bodyS3Key","bodySha256","bodyBytes","repoUrl","supersedesId","projectSlug","createdByAgentId","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deprecateSkill","tags":["Skills"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a skill as deprecated"}},"/api/v1/runners":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Runner"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listRunners","tags":["Runners"],"parameters":[{"in":"query","name":"serviceId","schema":{"type":"string"}},{"in":"query","name":"kind","schema":{"type":"string","enum":["agent-runner","orchestrator"]}},{"in":"query","name":"status","schema":{"type":"string","enum":["online","degraded","offline"]}}],"summary":"List registered runners","description":"Filterable by serviceId / kind / status. Ordered by freshest heartbeat first."},"post":{"responses":{"200":{"description":"Refreshed an existing runner","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Runner"}},"required":["data"]}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Runner"}},"required":["data"]}}}}},"operationId":"registerRunner","tags":["Runners"],"parameters":[],"summary":"Register or refresh a runner","description":"Idempotent upsert on the (kind, serviceId, baseUrl) identity (NULLS NOT DISTINCT). Re-registering the same box refreshes its version/status/heartbeat. Returns 201 when freshly created, 200 when an existing row was refreshed.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunnerRegister"}}}}}},"/api/v1/runners/{id}/heartbeat":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Runner"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"runnerHeartbeat","tags":["Runners"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Bump a runner's heartbeat","description":"Bumps last_heartbeat_at and optionally sets status. No audit row (high-frequency), mirroring agents/:id/heartbeat.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["online","degraded","offline"]}}}}}}}},"/api/v1/runners/{id}/usage":{"post":{"responses":{"200":{"description":"Upserted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UsageCeiling"}},"required":["data"]}}}},"404":{"description":"Unknown runner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"api_credit reported by a non-orchestrator runner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"postRunnerUsage","tags":["Runners"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Report a runner's usage-ceiling state","description":"Upserts the runner's state for one ceiling on the (runnerId, ceiling) key. `subscription` is valid for any runner; `api_credit` is valid ONLY for kind=orchestrator (impl boxes report subscription only) — an api_credit report from a non-orchestrator runner is rejected 422 USAGE_CEILING_NOT_APPLICABLE. Audited as runner.usage_report.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunnerUsageReport"}}}}}},"/api/v1/routing/lookup":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RoutingHit"}},"required":["data"]}}}},"400":{"description":"Bad key form (zero or more than one)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Target not found, or no runner owns it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unsupported artifact type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"routingLookup","tags":["Routing"],"parameters":[{"in":"query","name":"sliceId","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"}},{"in":"query","name":"artifactType","schema":{"type":"string","enum":["grpc_interface","rest_interface","table","outbox_topic","saga","sql_lookup","grpc","rest","outbox","sql"]}},{"in":"query","name":"artifactId","schema":{"type":"string","format":"uuid"}}],"summary":"Resolve the runner that owns a routing target","description":"Open read. Supply EXACTLY ONE of sliceId, serviceId, or (artifactType + artifactId). Returns the freshest non-offline runner's baseUrl + status for the producing service plus its active implementer agent."}},"/api/v1/usage":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UsageFanInRunner"}},"total":{"type":"number"}},"required":["data","total"]}}}}},"operationId":"getUsageFanIn","tags":["Usage"],"parameters":[{"in":"query","name":"serviceId","schema":{"type":"string"}},{"in":"query","name":"state","schema":{"type":"string","enum":["ok","warning","exhausted"]}}],"summary":"Operator fan-in of every runner's usage ceilings","description":"Open read. Returns each runner with its current usage ceilings, grouped per runner. Filterable by serviceId (runners driving that service) and state (only ceilings in that state; runners with no matching ceiling are excluded)."}},"/api/v1/notification-types":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NotificationType"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listNotificationTypes","tags":["Notification registry"],"parameters":[],"summary":"List the 12 notification types (D947 §2)"}},"/api/v1/notification-events":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NotificationEvent"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"listNotificationEvents","tags":["Notification registry"],"parameters":[{"in":"query","name":"status","schema":{"type":"string","enum":["proposed","approved","built","retired"]}},{"in":"query","name":"typeKey","schema":{"type":"string"}},{"in":"query","name":"producerServiceId","schema":{"type":"string"}},{"in":"query","name":"channel","schema":{"type":"string","enum":["email","sms","whatsapp","voice","push","in_app","oob"]}},{"in":"query","name":"emailRoute","schema":{"type":"string","enum":["nodii_only","prefer_tenant","prefer_tenant_guarded","none","provider_under_test"]}},{"in":"query","name":"includeRevisions","schema":{"type":"string","enum":["true","false"]}}],"summary":"List notification events (live revision per key by default)"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationEvent"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"422","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"proposeNotificationEvent","tags":["Notification registry"],"parameters":[],"summary":"Propose a new notification event","description":"Any producer service (or the operator) may propose. Status is always `proposed`; a request is filed to nodii-notification-service.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationEventPropose"}}}}}},"/api/v1/notification-events/export":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NotificationEvent"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}},"text/csv":{"schema":{"type":"string"}}}}},"operationId":"exportNotificationEvents","tags":["Notification registry"],"parameters":[{"in":"query","name":"format","schema":{"type":"string","enum":["json","csv"],"default":"json"}}],"summary":"Export every revision as JSON or CSV"}},"/api/v1/notification-events/by-key/{eventKey}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"current":{"$ref":"#/components/schemas/NotificationEvent"},"revisions":{"type":"array","items":{"$ref":"#/components/schemas/NotificationEvent"}}},"required":["current","revisions"]}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getNotificationEventByKey","tags":["Notification registry"],"parameters":[{"in":"path","name":"eventKey","schema":{"type":"string","minLength":1,"maxLength":200},"required":true}],"summary":"Get the live revision of an event key plus its history"}},"/api/v1/notification-events/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationEvent"}},"required":["data"]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getNotificationEvent","tags":["Notification registry"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get one notification event revision by id"}},"/api/v1/notification-events/{id}/revise":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationEvent"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"422","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"reviseNotificationEvent","tags":["Notification registry"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Append a new proposed revision of an event","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationEventRevise"}}}}}},"/api/v1/notification-events/{id}/approve":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationEvent"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"422","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"approveNotificationEvent","tags":["Notification registry"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Approve a proposed event and rule its mute/billing/email route","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationEventApprove"}}}}}},"/api/v1/notification-events/{id}/mark-built":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationEvent"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"422","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"markNotificationEventBuilt","tags":["Notification registry"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Record template keys + commit SHA for an approved event","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationEventMarkBuilt"}}}}}},"/api/v1/notification-events/{id}/retire":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationEvent"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"422","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"retireNotificationEvent","tags":["Notification registry"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Retire an event (needs replacedBy or a reason)","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationEventRetire"}}}}}},"/api/v1/workers":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Worker"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listWorkers","tags":["Workers"],"parameters":[{"in":"query","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"}},{"in":"query","name":"kind","schema":{"type":"string","enum":["cron","sweeper","consumer","saga-runner","outbox-drainer","queue-worker","reconciler","other"]}},{"in":"query","name":"status","schema":{"type":"string","enum":["planned","implementing","partially_implemented","implemented","deprecated"]}},{"in":"query","name":"processIsolation","schema":{"type":"string","enum":["compliant","non_compliant","unknown"]}},{"in":"query","name":"ratification","schema":{"type":"string","enum":["unratified","ratified","disputed"]}},{"in":"query","name":"tenancy","schema":{"type":"string","enum":["per-tenant","global"]}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":1000,"default":200}},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0}}],"summary":"List workers fleet-wide (filterable, paginated)","description":"Rows include contractRefs, ackBehavior and retryBackoff when recorded by the owning service."}},"/api/v1/workers/summary":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkerServiceSummary"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}}},"operationId":"getWorkersSummary","tags":["Workers"],"parameters":[],"summary":"Per-service worker counts by process isolation + ratification"}},"/api/v1/workers/by-key/{workerKey}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Worker"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getWorkerByKey","tags":["Workers"],"parameters":[{"in":"path","name":"workerKey","schema":{"type":"string","minLength":1,"maxLength":200},"required":true}],"summary":"Get a worker by its fleet-unique workerKey"}},"/api/v1/workers/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Worker"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getWorker","tags":["Workers"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a worker by id"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Worker"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateWorker","tags":["Workers"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Edit a worker's descriptive fields (owner or operator)","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkerPatch"}}}}},"delete":{"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"id":{"type":"string","format":"uuid"}},"required":["deleted","id"]}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deleteWorker","tags":["Workers"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true},{"in":"query","name":"force","schema":{"type":"string","enum":["true","false"]}}],"summary":"Delete a worker (owner or operator; ratified rows need ?force=true)"}},"/api/v1/services/{serviceId}/workers":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Worker"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listServiceWorkers","tags":["Workers"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"List the workers of one service"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Worker"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createWorker","tags":["Workers"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Register a worker for a service","description":"Owner service or operator only. Provenance is always `service`. An agent of the owning service lands the row `ratified` (a service registering its own worker ratifies it); an operator-created row lands `unratified` until the owner ratifies it.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkerCreate"}}}}}},"/api/v1/services/{serviceId}/workers/preseed":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkerPreseedResult"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"preseedWorkers","tags":["Workers"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Hub-scan pre-fill of a service's workers (operator only)","description":"One transaction. New keys insert as provenance=hub-scan, unratified. An existing unratified hub-scan row of the same service is refreshed; service-owned, ratified or disputed rows are skipped; a key owned by another service is skipped and reported in `conflicts`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkerPreseed"}}}}}},"/api/v1/workers/{id}/status":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Worker"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"setWorkerStatus","tags":["Workers"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Set a worker's lifecycle status (owner or operator)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["planned","implementing","partially_implemented","implemented","deprecated"]}},"required":["status"],"additionalProperties":false}}}}}},"/api/v1/workers/{id}/ratify":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Worker"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"ratifyWorker","tags":["Workers"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Ratify a worker row (owning service or operator only)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":4000}},"additionalProperties":false}}}}}},"/api/v1/workers/{id}/dispute":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Worker"}},"required":["data"]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"disputeWorker","tags":["Workers"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Dispute a worker row (owning service or operator only)","description":"Stores `reason` (plus the JSON of `corrections`, if given) in `ratificationNote` and flips ratification to `disputed`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkerDispute"}}}}}},"/api/v1/issues":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Issue"}},"total":{"type":"integer","minimum":0},"nextCursor":{"type":["string","null"]}},"required":["data","total","nextCursor"]}}}}},"operationId":"listIssues","tags":["Issues"],"parameters":[{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Filter by owning service (repeatable)"}},{"in":"query","name":"project","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"status","schema":{"anyOf":[{"type":"string","enum":["todo","in_progress","in_review","blocked","done","wont_do"]},{"type":"array","items":{"type":"string","enum":["todo","in_progress","in_review","blocked","done","wont_do"]}}]}},{"in":"query","name":"kind","schema":{"anyOf":[{"type":"string","enum":["feature","bug","chore","drift","request","verification"]},{"type":"array","items":{"type":"string","enum":["feature","bug","chore","drift","request","verification"]}}]}},{"in":"query","name":"priority","schema":{"anyOf":[{"type":"string","enum":["p0","p1","p2","p3"]},{"type":"array","items":{"type":"string","enum":["p0","p1","p2","p3"]}}]}},{"in":"query","name":"claimed","schema":{"type":"string","enum":["true","false"],"description":"true = live lease only; false = unclaimed"}},{"in":"query","name":"claimedBy","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":500}},{"in":"query","name":"cursor","schema":{"type":"string","maxLength":200}}],"summary":"List issues (newest first, keyset cursor)","description":"Filters: serviceId, project, status, kind, priority (each repeatable), claimed (live lease), claimedBy. Pass `nextCursor` back as `cursor`."},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IssueDetail"}},"required":["data"]}}}},"409":{"description":"Key already taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unknown service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createIssue","tags":["Issues"],"parameters":[],"summary":"File an issue against a service","description":"Key defaults to `<PROJECT>-<n>` (or a service-derived prefix) with n = 1 + the highest numeric suffix in use. New issues start in `todo`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"serviceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"title":{"type":"string","minLength":1,"maxLength":300},"bodyMd":{"type":"string","maxLength":200000},"kind":{"type":"string","enum":["feature","bug","chore","drift","request","verification"]},"priority":{"type":"string","enum":["p0","p1","p2","p3"]},"project":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9_-]{0,39}$"},"source":{"type":"string","enum":["manual","backlog_import","drift","request","ticket"]},"sourceRef":{"type":"string","maxLength":500},"links":{"$ref":"#/components/schemas/IssueLinks"},"key":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9._-]{0,99}$","description":"Explicit key; default `<PROJECT|SERVICE>-<n>`"},"onBehalfOf":{"type":"string","minLength":1,"maxLength":200}},"required":["serviceId","title"]}}}}}},"/api/v1/issues/{ref}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IssueDetail"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getIssue","tags":["Issues"],"parameters":[{"in":"path","name":"ref","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"},"required":true}],"summary":"Get an issue (by uuid or key) with body, events and lease state"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IssueDetail"}},"required":["data"]}}}},"403":{"description":"Lease held by another agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateIssue","tags":["Issues"],"parameters":[{"in":"path","name":"ref","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"},"required":true}],"summary":"Edit an issue's title / body / kind / priority / project / links","description":"Status changes go through POST /issues/:ref/transition. While another agent holds a live lease only that holder (or the operator) may edit.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"bodyMd":{"type":"string","maxLength":200000},"kind":{"type":"string","enum":["feature","bug","chore","drift","request","verification"]},"priority":{"type":"string","enum":["p0","p1","p2","p3"]},"project":{"type":["string","null"],"pattern":"^[A-Za-z][A-Za-z0-9_-]{0,39}$"},"links":{"$ref":"#/components/schemas/IssueLinks"},"onBehalfOf":{"type":"string","minLength":1,"maxLength":200}}}}}}}},"/api/v1/issues/{ref}/transition":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IssueDetail"}},"required":["data"]}}}},"403":{"description":"Lease held by another agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Illegal transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"transitionIssue","tags":["Issues"],"parameters":[{"in":"path","name":"ref","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"},"required":true}],"summary":"Move an issue along the enforced status map","description":"todo→{in_progress,blocked,done,wont_do}; in_progress→{in_review,blocked,todo,done,wont_do}; in_review→{in_progress,blocked,done,wont_do}; blocked→{todo,in_progress,wont_do}; done→todo; wont_do→todo. Closing (done/wont_do) ends any lease. Illegal moves return 409 ISSUE_ILLEGAL_TRANSITION with the allowed set. Set releaseClaim=true to release the current lease in the same transaction; staff need devops.issues.write, and an agent may release only its own claim.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","enum":["todo","in_progress","in_review","blocked","done","wont_do"]},"note":{"type":"string","maxLength":10000},"releaseClaim":{"type":"boolean","const":true,"description":"Release the current issue claim atomically"},"releaseReason":{"type":"string","minLength":1,"maxLength":10000,"description":"Optional audit reason for releasing the claim"},"onBehalfOf":{"type":"string","minLength":1,"maxLength":200}},"required":["to"]}}}}}},"/api/v1/issues/{ref}/claim":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IssueDetail"}},"required":["data"]}}}},"403":{"description":"agentId differs from the signer (non-operator)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Lease held by another agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Issue is closed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"claimIssue","tags":["Issues"],"parameters":[{"in":"path","name":"ref","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"},"required":true}],"summary":"Lease an issue for an agent acting on behalf of a person","description":"Refused with 409 LEASE_HELD while another agent's lease is live; an expired lease may be taken over. Claiming a `todo` issue moves it to `in_progress`. Default TTL 30 min, max 24 h; renew via heartbeat.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid","description":"Defaults to the signing agent; operator may claim for another"},"onBehalfOf":{"type":"string","minLength":1,"maxLength":200,"description":"The named person this agent acts for (D1367 §1)"},"ttlMinutes":{"type":"integer","exclusiveMinimum":0,"maximum":1440}},"required":["onBehalfOf"]}}}}}},"/api/v1/issues/{ref}/heartbeat":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IssueDetail"}},"required":["data"]}}}},"403":{"description":"Lease not held by this agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"heartbeatIssue","tags":["Issues"],"parameters":[{"in":"path","name":"ref","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"},"required":true}],"summary":"Renew the caller's lease on an issue","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ttlMinutes":{"type":"integer","exclusiveMinimum":0,"maximum":1440}}}}}}}},"/api/v1/issues/{ref}/release":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IssueDetail"}},"required":["data"]}}}},"403":{"description":"Lease not held by this agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"releaseIssue","tags":["Issues"],"parameters":[{"in":"path","name":"ref","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"},"required":true}],"summary":"Release a lease without closing the issue","description":"Holder or operator only. An `in_progress` issue returns to `todo`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":10000},"onBehalfOf":{"type":"string","minLength":1,"maxLength":200}}}}}}}},"/api/v1/issues/{ref}/comment":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IssueEvent"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"commentOnIssue","tags":["Issues"],"parameters":[{"in":"path","name":"ref","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"},"required":true}],"summary":"Append a comment to an issue's activity feed","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":10000},"onBehalfOf":{"type":"string","minLength":1,"maxLength":200}},"required":["body"]}}}}}},"/api/v1/backlogs":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Backlog"}],"properties":{"itemCount":{"type":"integer"}},"required":["itemCount"]}},"total":{"type":"integer"}},"required":["data","total"]}}}}},"operationId":"listBacklogs","tags":["Backlogs"],"parameters":[{"in":"query","name":"serviceId","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"in":"query","name":"project","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}],"summary":"List backlogs with item counts"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BacklogDetail"}},"required":["data"]}}}},"409":{"description":"Slug taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unknown service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createBacklog","tags":["Backlogs"],"parameters":[],"summary":"Create a named, ordered backlog for a service or project","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,62}$"},"name":{"type":"string","minLength":1,"maxLength":200},"serviceId":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"project":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9_-]{0,39}$"},"description":{"type":"string","maxLength":2000}},"required":["slug","name"]}}}}}},"/api/v1/backlogs/{ref}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BacklogDetail"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getBacklog","tags":["Backlogs"],"parameters":[{"in":"path","name":"ref","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9-]{0,99}$"},"required":true}],"summary":"Get a backlog (by uuid or slug) with its items in order"}},"/api/v1/backlogs/{ref}/items":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BacklogDetail"}},"required":["data"]}}}},"404":{"description":"Backlog or issue not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Already in this backlog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Anchor not in this backlog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"addBacklogItem","tags":["Backlogs"],"parameters":[{"in":"path","name":"ref","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9-]{0,99}$"},"required":true}],"summary":"Add an issue to a backlog (appended unless anchored)","description":"Positions are gap integers (1024 apart), renumbered when a gap closes.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"issueId":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$","description":"Issue uuid or key"},"beforeIssueId":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"},"afterIssueId":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"}},"required":["issueId"]}}}}}},"/api/v1/backlogs/{ref}/items/{issueRef}/move":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BacklogDetail"}},"required":["data"]}}}},"404":{"description":"Backlog / issue / item not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Anchor not in this backlog, or anchor is the item itself","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"moveBacklogItem","tags":["Backlogs"],"parameters":[{"in":"path","name":"ref","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9-]{0,99}$"},"required":true},{"in":"path","name":"issueRef","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"},"required":true}],"summary":"Move an item directly before or after another item","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"beforeIssueId":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"},"afterIssueId":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"}}}}}}}},"/api/v1/backlogs/{ref}/items/{issueRef}":{"delete":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BacklogDetail"}},"required":["data"]}}}},"404":{"description":"Backlog / issue / item not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"removeBacklogItem","tags":["Backlogs"],"parameters":[{"in":"path","name":"ref","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9-]{0,99}$"},"required":true},{"in":"path","name":"issueRef","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"},"required":true}],"summary":"Remove an issue from a backlog (the issue itself is kept)"}},"/api/v1/services/{id}/work":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ServiceWorkSummary"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getServiceWork","tags":["Issues"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Open issues by status, live claims, and the oldest open issue"}},"/api/v1/builds":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BuildView"}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listBuilds","tags":["Delivery"],"parameters":[{"in":"query","name":"serviceId","schema":{"type":"string"}},{"in":"query","name":"environment","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string"}},{"in":"query","name":"blocked","schema":{"type":"string","enum":["true","false"]}},{"in":"query","name":"since","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"cursor","schema":{"type":"string","maxLength":200}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":200}}],"summary":"List builds (deploy runs), newest first","description":"Filters: serviceId, environment, status (deploy status), blocked, since (started at or after), comma-separated for multi-value. Keyset paged: pass the returned nextCursor back as cursor."}},"/api/v1/builds/summary":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BuildSummary"}}},"required":["data"]}}}}},"operationId":"getBuildSummary","tags":["Delivery"],"parameters":[],"summary":"Summarize all builds by service and environment","description":"Returns the latest build and CI/deploy status counts computed over the complete build history."}},"/api/v1/builds/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BuildDetail"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getBuild","tags":["Delivery"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a build with the changes it carries"}},"/api/v1/builds/report":{"post":{"responses":{"200":{"description":"Updated an existing build","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Build"}},"required":["data"]}}}},"201":{"description":"Recorded a new build","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Build"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"repo / runId disagree with runUrl or the service's repo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"reportBuild","tags":["Delivery"],"parameters":[],"summary":"Report a deploy run (nodii-infra deploy workflow)","description":"Idempotent upsert keyed by (repo, runId); repo and runId are read from runUrl when omitted and must agree with it. Carries the image digest the poller cannot see (request 7c4c76bd).","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildReport"}}}}}},"/api/v1/changes":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChangeView"}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listChanges","tags":["Delivery"],"parameters":[{"in":"query","name":"serviceId","schema":{"type":"string"}},{"in":"query","name":"mark","schema":{"type":"string"}},{"in":"query","name":"since","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"touches","schema":{"type":"string","enum":["proto","openapi","migration","outbox-contract","rbac-catalog","frontend","docs-only","ci-only","tests-only"]}},{"in":"query","name":"userVisible","schema":{"type":"string","enum":["true","false"]}},{"in":"query","name":"cursor","schema":{"type":"string","maxLength":200}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":200}}],"summary":"List changes (merged PRs), newest merge first","description":"Filters: serviceId, mark (comma-separated), since (merged at or after), touches (one classifier tag), userVisible. Keyset paged via nextCursor."}},"/api/v1/changes/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChangeDetail"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getChange","tags":["Delivery"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a change with the builds that shipped it and its paths"}},"/api/v1/changes/{id}/mark":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Change"}},"required":["data"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Reason missing, or fixedByChangeId invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"markChange","tags":["Delivery"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Mark a change verified / broken / rolled back","description":"Staff need devops.releases.verify to mark Verified; other marks and userVisible changes need devops.changes.write. A reason is required for broken and rolled_back. fixedByChangeId (only with broken) names the change that fixes it: a build carrying both is not blocked. Every call is audited as change.mark with the previous and new values.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeMarkInput"}}}}}},"/api/v1/services/{serviceId}/delivery":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ServiceDelivery"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getServiceDelivery","tags":["Delivery"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"Delivery summary: last build per environment, change counts"}},"/api/v1/delivery/poll-state":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryPollState"}}},"required":["data"]}}}}},"operationId":"listDeliveryPollState","tags":["Delivery"],"parameters":[],"summary":"The GitHub poller's per-repo high-water marks and last errors"}},"/api/v1/runtime":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RuntimeObservation"}}},"required":["data"]}}}}},"operationId":"listRuntimeInventory","tags":["Runtime"],"parameters":[],"summary":"List the latest runtime inventory across the fleet"}},"/api/v1/services/{id}/runtime":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RuntimeObservation"}}},"required":["data"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getServiceRuntime","tags":["Runtime"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"List the latest runtime inventory for a service"}},"/api/v1/lanes/summary":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"count":{"type":"number"}},"required":["status","kind","count"]}}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getLaneSummary","tags":["Lanes"],"parameters":[],"summary":"Count lanes by phase and kind"}},"/api/v1/lanes":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"stuck":{"type":"boolean"}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt","stuck"]}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listLanes","tags":["Lanes"],"parameters":[{"in":"query","name":"kind","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string"}},{"in":"query","name":"machine","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"agent","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"waiting-on","schema":{"type":"string","enum":["backend","frontend"]}},{"in":"query","name":"stuck","schema":{"type":"string","enum":["true","false"]}},{"in":"query","name":"cursor","schema":{"type":"string","maxLength":500}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"summary":"List lanes with cursor pagination"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createLane","tags":["Lanes"],"parameters":[],"summary":"Create a queued lane and workflow steps","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9-]*$"},"title":{"type":"string","minLength":1,"maxLength":500},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string","minLength":1},"minItems":1},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string","minLength":1},"worktree":{"type":"string","minLength":1},"issueIds":{"type":"array","items":{"type":"string","format":"uuid"},"default":[]},"stepLimitSeconds":{"type":"integer","exclusiveMinimum":0,"maximum":604800},"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"required":["key","title","kind","side","repos","agentId","machineId","branch","worktree"]}}}}}},"/api/v1/lanes/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"stuck":{"type":"boolean"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"laneId":{"type":"string","format":"uuid"},"side":{"type":"string","enum":["backend","frontend","both"]},"stepKey":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"state":{"type":"string","enum":["waiting","current","done","blocked"]},"startedAt":{"type":["string","null"]},"completedAt":{"type":["string","null"]},"blockedAt":{"type":["string","null"]}},"required":["id","laneId","side","stepKey","label","position","state","startedAt","completedAt","blockedAt"]}},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"laneId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["lane_started","step_started","step_done","step_blocked","evidence","heartbeat","stuck","escalated","prioritized","deprioritized","stopped","acknowledged"]},"actorAgentId":{"type":["string","null"],"format":"uuid"},"actorRef":{"type":["string","null"]},"actorPersonId":{"type":["string","null"]},"via":{"type":"string"},"metadata":{"type":"object","additionalProperties":{}},"episodeKey":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","laneId","type","actorAgentId","actorRef","actorPersonId","via","metadata","episodeKey","createdAt"]}},"issues":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"}},"required":["id","key","title"]}},"acknowledgement":{"type":["object","null"],"properties":{"laneId":{"type":"string","format":"uuid"},"acknowledgedByAgentId":{"type":["string","null"],"format":"uuid"},"acknowledgedByPersonId":{"type":["string","null"]},"note":{"type":["string","null"]},"acknowledgedAt":{"type":"string"}},"required":["laneId","acknowledgedByAgentId","acknowledgedByPersonId","note","acknowledgedAt"]}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt","stuck","steps","events","issues","acknowledgement"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getLane","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9-]*$"}]},"required":true}],"summary":"Get lane steps and timeline"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateLane","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9-]*$"}]},"required":true}],"summary":"Update editable lane fields","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":500},"repos":{"type":"array","items":{"type":"string","minLength":1},"minItems":1},"agentId":{"type":"string","format":"uuid"},"branch":{"type":"string","minLength":1},"worktree":{"type":"string","minLength":1},"issueIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"additionalProperties":false}}}}}},"/api/v1/lanes/{id}/start":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"startLane","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9-]*$"}]},"required":true}],"summary":"Start a queued lane","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"default":{"via":"nodii-dev"}}}}}}},"/api/v1/lanes/{id}/steps/{stepId}/done":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"laneId":{"type":"string","format":"uuid"},"side":{"type":"string","enum":["backend","frontend","both"]},"stepKey":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"state":{"type":"string","enum":["waiting","current","done","blocked"]},"startedAt":{"type":["string","null"]},"completedAt":{"type":["string","null"]},"blockedAt":{"type":["string","null"]}},"required":["id","laneId","side","stepKey","label","position","state","startedAt","completedAt","blockedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"completeLaneStep","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9-]*$"}]},"required":true},{"in":"path","name":"stepId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Complete the current lane step","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"default":{"via":"nodii-dev"}}}}}}},"/api/v1/lanes/{id}/steps/{stepId}/block":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"laneId":{"type":"string","format":"uuid"},"side":{"type":"string","enum":["backend","frontend","both"]},"stepKey":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"state":{"type":"string","enum":["waiting","current","done","blocked"]},"startedAt":{"type":["string","null"]},"completedAt":{"type":["string","null"]},"blockedAt":{"type":["string","null"]}},"required":["id","laneId","side","stepKey","label","position","state","startedAt","completedAt","blockedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"blockLaneStep","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9-]*$"}]},"required":true},{"in":"path","name":"stepId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Block the current lane step","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"default":{"via":"nodii-dev"}}}}}}},"/api/v1/lanes/{id}/steps/{stepId}/start":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"laneId":{"type":"string","format":"uuid"},"side":{"type":"string","enum":["backend","frontend","both"]},"stepKey":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"state":{"type":"string","enum":["waiting","current","done","blocked"]},"startedAt":{"type":["string","null"]},"completedAt":{"type":["string","null"]},"blockedAt":{"type":["string","null"]}},"required":["id","laneId","side","stepKey","label","position","state","startedAt","completedAt","blockedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"startLaneStep","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9-]*$"}]},"required":true},{"in":"path","name":"stepId","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Start or resume a lane step","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"default":{"via":"nodii-dev"}}}}}}},"/api/v1/lanes/{id}/evidence":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"stuck":{"type":"boolean"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"laneId":{"type":"string","format":"uuid"},"side":{"type":"string","enum":["backend","frontend","both"]},"stepKey":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"state":{"type":"string","enum":["waiting","current","done","blocked"]},"startedAt":{"type":["string","null"]},"completedAt":{"type":["string","null"]},"blockedAt":{"type":["string","null"]}},"required":["id","laneId","side","stepKey","label","position","state","startedAt","completedAt","blockedAt"]}},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"laneId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["lane_started","step_started","step_done","step_blocked","evidence","heartbeat","stuck","escalated","prioritized","deprioritized","stopped","acknowledged"]},"actorAgentId":{"type":["string","null"],"format":"uuid"},"actorRef":{"type":["string","null"]},"actorPersonId":{"type":["string","null"]},"via":{"type":"string"},"metadata":{"type":"object","additionalProperties":{}},"episodeKey":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","laneId","type","actorAgentId","actorRef","actorPersonId","via","metadata","episodeKey","createdAt"]}},"issues":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"}},"required":["id","key","title"]}},"acknowledgement":{"type":["object","null"],"properties":{"laneId":{"type":"string","format":"uuid"},"acknowledgedByAgentId":{"type":["string","null"],"format":"uuid"},"acknowledgedByPersonId":{"type":["string","null"]},"note":{"type":["string","null"]},"acknowledgedAt":{"type":"string"}},"required":["laneId","acknowledgedByAgentId","acknowledgedByPersonId","note","acknowledgedAt"]}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt","stuck","steps","events","issues","acknowledgement"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"addLaneEvidence","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9-]*$"}]},"required":true}],"summary":"Append lane evidence","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["pr","commit","figma_frame","deploy","dev_check"]},"url":{"type":"string","format":"uri"},"ref":{"type":"string","minLength":1},"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"required":["kind"]}}}}}},"/api/v1/lanes/{id}/heartbeat":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"stuck":{"type":"boolean"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"laneId":{"type":"string","format":"uuid"},"side":{"type":"string","enum":["backend","frontend","both"]},"stepKey":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"state":{"type":"string","enum":["waiting","current","done","blocked"]},"startedAt":{"type":["string","null"]},"completedAt":{"type":["string","null"]},"blockedAt":{"type":["string","null"]}},"required":["id","laneId","side","stepKey","label","position","state","startedAt","completedAt","blockedAt"]}},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"laneId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["lane_started","step_started","step_done","step_blocked","evidence","heartbeat","stuck","escalated","prioritized","deprioritized","stopped","acknowledged"]},"actorAgentId":{"type":["string","null"],"format":"uuid"},"actorRef":{"type":["string","null"]},"actorPersonId":{"type":["string","null"]},"via":{"type":"string"},"metadata":{"type":"object","additionalProperties":{}},"episodeKey":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","laneId","type","actorAgentId","actorRef","actorPersonId","via","metadata","episodeKey","createdAt"]}},"issues":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"}},"required":["id","key","title"]}},"acknowledgement":{"type":["object","null"],"properties":{"laneId":{"type":"string","format":"uuid"},"acknowledgedByAgentId":{"type":["string","null"],"format":"uuid"},"acknowledgedByPersonId":{"type":["string","null"]},"note":{"type":["string","null"]},"acknowledgedAt":{"type":"string"}},"required":["laneId","acknowledgedByAgentId","acknowledgedByPersonId","note","acknowledgedAt"]}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt","stuck","steps","events","issues","acknowledgement"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"heartbeatLane","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9-]*$"}]},"required":true}],"summary":"Heartbeat a lane","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":500},"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"default":{"via":"nodii-dev"}}}}}}},"/api/v1/lanes/{id}/land":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"landLane","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9-]*$"}]},"required":true}],"summary":"Record that lane work reached main","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"default":{"via":"nodii-dev"}}}}}}},"/api/v1/lanes/{id}/review":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"reviewLane","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9-]*$"}]},"required":true}],"summary":"Move built lane into review","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"default":{"via":"nodii-dev"}}}}}}},"/api/v1/lanes/{id}/verify":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"verifyLaneOnDev","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9-]*$"}]},"required":true}],"summary":"Verify lane on dev with dev-check evidence","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"ref":{"type":"string","minLength":1},"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}}}}}}}},"/api/v1/lanes/{id}/prioritize":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"prioritizeLane","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9-]*$"}]},"required":true}],"summary":"prioritize lane","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500},"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"required":["reason"]}}}}}},"/api/v1/lanes/{id}/deprioritize":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"deprioritizeLane","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9-]*$"}]},"required":true}],"summary":"deprioritize lane","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500},"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"required":["reason"]}}}}}},"/api/v1/lanes/{id}/stop":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"stopLane","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9-]*$"}]},"required":true}],"summary":"Stop a lane as the operator","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":4000},"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}},"required":["reason"]}}}}}},"/api/v1/built":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["dev_fix","new_build","docs_change","uat_fix","prod_fix"]},"side":{"type":"string","enum":["backend","frontend","both"]},"repos":{"type":"array","items":{"type":"string"}},"agentId":{"type":"string","format":"uuid"},"machineId":{"type":"string","format":"uuid"},"branch":{"type":"string"},"worktree":{"type":"string"},"queuePosition":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"status":{"type":"string","enum":["queued","building","built","review","on_main","on_dev","stopped"]},"currentBackendStep":{"type":["string","null"]},"currentFrontendStep":{"type":["string","null"]},"stepStartedAt":{"type":["string","null"]},"lastHeartbeatAt":{"type":["string","null"]},"stepLimitSeconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"startedAt":{"type":["string","null"]},"stoppedByAgentId":{"type":["string","null"],"format":"uuid"},"stoppedByPersonId":{"type":["string","null"]},"stopReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"acknowledgement":{"type":["object","null"],"properties":{"laneId":{"type":"string","format":"uuid"},"acknowledgedByAgentId":{"type":["string","null"],"format":"uuid"},"acknowledgedByPersonId":{"type":["string","null"]},"note":{"type":["string","null"]},"acknowledgedAt":{"type":"string"}},"required":["laneId","acknowledgedByAgentId","acknowledgedByPersonId","note","acknowledgedAt"]}},"required":["id","key","title","kind","side","repos","agentId","machineId","branch","worktree","queuePosition","status","currentBackendStep","currentFrontendStep","stepStartedAt","lastHeartbeatAt","stepLimitSeconds","startedAt","stoppedByAgentId","stoppedByPersonId","stopReason","createdAt","updatedAt","acknowledgement"]}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listBuiltLanes","tags":["Lanes"],"parameters":[{"in":"query","name":"cursor","schema":{"type":"string","maxLength":500}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"in":"query","name":"includeAcknowledged","schema":{"type":"string","enum":["true","false"],"default":"false"}}],"summary":"List built lanes with cursor pagination"}},"/api/v1/built/{id}/acknowledge":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"laneId":{"type":"string","format":"uuid"},"acknowledgedByAgentId":{"type":["string","null"],"format":"uuid"},"acknowledgedByPersonId":{"type":["string","null"]},"note":{"type":["string","null"]},"acknowledgedAt":{"type":"string"}},"required":["laneId","acknowledgedByAgentId","acknowledgedByPersonId","note","acknowledgedAt"]}}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"acknowledgeBuiltLane","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9-]*$"}]},"required":true}],"summary":"Acknowledge one on-dev lane","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":["string","null"],"maxLength":4000},"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"}}}}}}}},"/api/v1/built/acknowledge":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"laneId":{"type":"string","format":"uuid"},"acknowledgedByAgentId":{"type":["string","null"],"format":"uuid"},"acknowledgedByPersonId":{"type":["string","null"]},"note":{"type":["string","null"]},"acknowledgedAt":{"type":"string"}},"required":["laneId","acknowledgedByAgentId","acknowledgedByPersonId","note","acknowledgedAt"]}}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"bulkAcknowledgeBuiltLanes","tags":["Lanes"],"parameters":[],"summary":"Acknowledge on-dev lanes in bulk","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":["string","null"],"maxLength":4000},"via":{"type":"string","const":"nodii-dev","default":"nodii-dev"},"laneIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":200}},"required":["laneIds"]}}}}}},"/api/v1/machines":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Machine"}},"total":{"type":"number"}},"required":["data","total"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"listMachines","tags":["Lanes"],"parameters":[],"summary":"List machines"},"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Machine"}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"createMachine","tags":["Lanes"],"parameters":[],"summary":"Create a machine with its coordinator","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"coordinatorAgentId":{"type":"string","format":"uuid"},"heavySlotTotal":{"type":"integer","exclusiveMinimum":0,"maximum":128,"default":1},"hostFacts":{"type":"object","additionalProperties":{},"default":{}},"memoryFacts":{"type":"object","additionalProperties":{},"default":{}}},"required":["name","coordinatorAgentId"]}}}}}},"/api/v1/machines/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"getMachine","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Get a machine, agents, and lanes"},"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Machine"}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"updateMachine","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Update machine facts and capacity","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"heavySlotTotal":{"type":"integer","exclusiveMinimum":0,"maximum":128,"default":1},"hostFacts":{"type":"object","additionalProperties":{},"default":{}},"memoryFacts":{"type":"object","additionalProperties":{},"default":{}}},"additionalProperties":false}}}}}},"/api/v1/machines/{id}/agents":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"assignAgentToMachine","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Assign an agent and home repository to a machine","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"},"homeRepo":{"type":"string","minLength":1,"maxLength":300}},"required":["agentId","homeRepo"]}}}}}},"/api/v1/machines/{id}/report":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Machine"}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"reportMachine","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Report machine resources","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"hostFacts":{"type":"object","additionalProperties":{}},"memoryFacts":{"type":"object","additionalProperties":{}},"heavySlotTotal":{"type":"integer","exclusiveMinimum":0,"maximum":128}},"required":["hostFacts","memoryFacts","heavySlotTotal"]}}}}}},"/api/v1/machines/{id}/coordinator":{"put":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Machine"}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"setMachineCoordinator","tags":["Lanes"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"summary":"Set the machine's sole coordinator","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"}},"required":["agentId"]}}}}}},"/api/v1/services/{id}/gate":{"get":{"responses":{"200":{"description":"Gate verdict"}},"operationId":"getServiceGate","tags":["Inbox"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}]}},"/api/v1/gate":{"get":{"responses":{"200":{"description":"Fleet gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FleetGateResponse"}}}}},"operationId":"getFleetGate","tags":["Inbox"],"parameters":[]}},"/api/v1/gate/dry-run":{"get":{"responses":{"200":{"description":"Enforcement dry run"}},"operationId":"getGateDryRun","tags":["Inbox"],"parameters":[]}},"/api/v1/inbox":{"get":{"responses":{"200":{"description":"Merged FIFO inbox"}},"operationId":"listInbox","tags":["Inbox"],"parameters":[{"in":"query","name":"serviceId","schema":{"type":"string","minLength":1},"required":true},{"in":"query","name":"kind","schema":{"type":"string","enum":["drift","request","question","lane_escalation","credential_expiry"]},"required":false},{"in":"query","name":"cursor","schema":{"type":"string"},"required":false},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false}]}},"/api/v1/inbox/{kind}/{id}/answer":{"post":{"responses":{"200":{"description":"Answered"}},"operationId":"answerInboxItem","tags":["Inbox"],"parameters":[{"in":"path","name":"kind","schema":{"type":"string","enum":["drift","request","question","lane_escalation","credential_expiry"]},"required":true},{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"bodyMd":{"type":"string","minLength":1},"onBehalfOf":{"type":"string","minLength":1}},"required":["bodyMd"]}}}}}},"/api/v1/inbox/{kind}/{id}/assign":{"post":{"responses":{"200":{"description":"Assigned"},"409":{"description":"Project started"}},"operationId":"assignInboxItem","tags":["Inbox"],"parameters":[{"in":"path","name":"kind","schema":{"type":"string","enum":["drift","request","question","lane_escalation","credential_expiry"]},"required":true},{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"reason":{"type":"string","minLength":1},"notifyService":{"type":"boolean"}},"required":["projectId","reason","notifyService"]}}}}}},"/api/v1/inbox/{kind}/{id}/rule":{"post":{"responses":{"201":{"description":"Decision locked and item resolved"}},"operationId":"ruleInboxItemIntoDecision","tags":["Inbox"],"parameters":[{"in":"path","name":"kind","schema":{"type":"string","enum":["drift","request","question","lane_escalation","credential_expiry"]},"required":true},{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"object","properties":{"id":{"type":"string","pattern":"^([a-z][a-z0-9_-]*-)?D\\d+$"},"title":{"type":"string","minLength":1},"module":{"type":"string","minLength":1},"bodyMd":{"type":"string","minLength":1},"topicTags":{"type":"array","items":{"type":"string"},"default":[]}},"required":["id","title","module","bodyMd"]},"amends":{"type":"array","items":{"type":"string"}},"resolutionMd":{"type":"string","minLength":1}},"required":["decision","resolutionMd"]}}}}}},"/api/v1/refresher/{serviceId}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"type":"object"}}}}},"operationId":"getServiceRefresher","tags":["Composite"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true},{"in":"query","name":"include_audit","schema":{"type":"string","enum":["true","false"]}},{"in":"query","name":"changelog_limit","schema":{"type":"string","pattern":"^\\d+$"}},{"in":"query","name":"drift_limit","schema":{"type":"string","pattern":"^\\d+$"}}],"summary":"Single-call hydration: everything an agent needs to start working on a service","description":"Parallel query plan. Returns service + health + doctrine + decisions + feature docs + tables + REST/gRPC + sagas + outbox + approval kinds + libs + requests + drift + recent changelog + edges."}},"/api/v1/impact/{artifactType}/{id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Unsupported artifact type","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Artifact not found","content":{"application/json":{"schema":{"type":"object"}}}}},"operationId":"getImpact","tags":["Composite"],"parameters":[{"in":"path","name":"artifactType","schema":{"type":"string","enum":["grpc_interface","rest_interface","outbox_topic","table","saga","decision","library","approval_kind"]},"required":true},{"in":"path","name":"id","schema":{"type":"string","minLength":1},"required":true}],"summary":"What depends on this artifact?"}},"/api/v1/search":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Empty query","content":{"application/json":{"schema":{"type":"object"}}}}},"operationId":"search","tags":["Composite"],"parameters":[{"in":"query","name":"q","schema":{"type":"string","minLength":1},"required":true},{"in":"query","name":"kind","schema":{"anyOf":[{"type":"string","enum":["decision","doctrine","feature_doc","rest_interface","grpc_interface"]},{"type":"array","items":{"type":"string","enum":["decision","doctrine","feature_doc","rest_interface","grpc_interface"]}}]},"required":false},{"in":"query","name":"serviceId","schema":{"type":"string"},"required":false},{"in":"query","name":"limit","schema":{"type":"string","pattern":"^\\d+$"},"required":false}],"summary":"Full-text search across decisions, doctrine, feature docs, REST + gRPC"}},"/api/v1/services/{serviceId}/unblock-surface":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"type":"object"}}}}},"operationId":"getUnblockSurface","tags":["Composite"],"parameters":[{"in":"path","name":"serviceId","schema":{"type":"string","pattern":"^[a-z][a-z0-9_-]*$"},"required":true}],"summary":"What is blocking this service? One call returns all open drift, requests, open questions, and a next-action recommendation per item.","description":"Composite read that replaces the 5-query Python coordinator sweep. All items are open/unresolved only. Sorted breaking→consumer-visible→local for drift, oldest-first for requests."}}},"security":[{"oauth":[]}]}