backend-skeleton 1.0.0-beta.1

package/schemas/feature-contract.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:feature-contract:1",
+  "title": "backend-skeleton per-feature contract (meta-schema)",
+  "description": "Validates the SHAPE of specs/<feature_id>/contracts/<feature_id>.schema.json itself -- not a payload. See contracts/validate.mjs for payload validation against a specific operation inside a contract that already passed this meta-schema.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["sbf_contract", "feature_id", "feature_uid", "source", "operations", "warnings", "completeness"],
+  "properties": {
+    "sbf_contract": { "const": "4" },
+    "feature_id": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" },
+    "feature_uid": { "type": "string", "format": "uuid" },
+    "source": {
+      "type": "object",
+      "required": ["adapter", "module", "provenance"],
+      "properties": {
+        "adapter": { "type": ["string", "null"] },
+        "module": { "type": ["string", "null"] },
+        "provenance": { "type": "string" }
+      }
+    },
+    "operations": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["verb", "path", "pathParams", "body", "provenance"],
+        "properties": {
+          "verb": { "type": "string" },
+          "path": { "type": "string" },
+          "pathParams": { "type": "object" },
+          "body": { "enum": [true, false, "unknown"] },
+          "provenance": { "type": "string" },
+          "requestBodySchema": {
+            "description": "A2: the operation's request body projected from a real OpenAPI 3.1 document, fully inlined (no $ref) -- see contracts/openapi.mjs's inlineSchema(). Present only when reconciliation matched/adopted this operation AND its application/json schema resolved; omitted otherwise. Not deeply validated as 'is this a valid JSON Schema' here -- that would need a schema-of-schemas, out of scope.",
+            "type": "object"
+          },
+          "requestBodyRequired": { "type": "boolean" },
+          "responseSchema": {
+            "description": "A3: all documented 2xx application/json response schemas for this operation, fully inlined (no $ref); an anyOf union when 2+ distinct shapes are documented. Present only when matched/adopted AND at least one resolved.",
+            "type": "object"
+          },
+          "errorSchema": {
+            "description": "A3: all documented 4xx/5xx application/json response schemas for this operation, fully inlined (no $ref); an anyOf union when 2+ distinct shapes are documented. Present only when matched/adopted AND at least one resolved.",
+            "type": "object"
+          }
+        }
+      }
+    },
+    "warnings": {
+      "description": "A5: structured, not bare strings -- see contracts/completeness.mjs's WARNING_CODES for the known code table.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["code", "severity", "subject", "message", "detail"],
+        "properties": {
+          "code": { "type": "string", "pattern": "^CONTRACT_[A-Z_]+$" },
+          "severity": { "enum": ["error", "warn"] },
+          "subject": { "type": ["string", "null"] },
+          "message": { "type": "string" },
+          "detail": { "type": "object" }
+        }
+      }
+    },
+    "completeness": {
+      "description": "A5: derived from operations/warnings alone, independent of any recorded waiver -- see contracts/completeness.mjs's classifyContract().",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "operation_count", "endpoint_count"],
+      "properties": {
+        "status": { "enum": ["complete", "partial", "blocked"] },
+        "operation_count": { "type": "integer", "minimum": 0 },
+        "endpoint_count": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

package/schemas/feature-index.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:feature-index:1",
+  "title": "backend-skeleton feature index (.sbf/feature-index.json)",
+  "description": "D6 (D-feature-lifecycle): first real schema for this file -- previously unvalidated. `by_uid[uid]` was already an array (single-element only, written by `feature init`) -- D6 is its first real consumer: `bskel feature rename` appends rather than replaces, so the array IS the rename history (last entry is the current feature_id). `merged_into` is new, written by `bskel feature link` -- index-only, never implies the aliased feature_id's own specs/.sbf/ artifacts were touched or merged.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "by_uid"],
+  "properties": {
+    "schema": { "const": "sbf.feature-index/1" },
+    "by_uid": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "items": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" },
+        "minItems": 1
+      }
+    },
+    "merged_into": {
+      "type": "object",
+      "description": "written by `bskel feature link <keepId> <aliasId>` -- maps aliasId -> keepId. Deliberately does not imply aliasId's own specs/.sbf/ files were touched; a human decides what to do with the two features' actual content.",
+      "additionalProperties": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" }
+    }
+  }
+}

package/schemas/feature.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:feature:1",
+  "title": "backend-skeleton feature record (specs/<feature_id>/feature.json)",
+  "description": "D6 (D-feature-lifecycle): first real schema for this file -- previously unvalidated. archived_at/archived_reason are new, added alongside `bskel feature archive`.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "feature_id", "feature_uid", "created_at"],
+  "properties": {
+    "schema": { "const": "sbf.feature/1" },
+    "feature_id": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" },
+    "feature_uid": { "type": "string", "format": "uuid" },
+    "created_at": { "type": "string" },
+    "archived_at": { "type": "string", "description": "set by `bskel feature archive` -- a soft-delete marker, not a filesystem move. Present iff archived_reason is." },
+    "archived_reason": { "type": "string", "description": "required alongside archived_at -- every archive is auditable, matching this project's --force/--reason convention elsewhere (O2, S4)." }
+  }
+}

package/schemas/gate-event.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:gate-event:1",
+  "title": "backend-skeleton gate history event",
+  "description": "One line of a .sbf/<feature>.history.jsonl file, appended by lib/state.mjs's setGate() every time a gate's current-state snapshot changes. Deliberately does NOT include a 'stale' event -- staleness is derived at READ time (lib/gates.mjs's requireGate()), never written to disk, so there is nothing to log an event for; only the 4 real write-time transitions (pass/awaiting_disposition/force/revoke) appear here. See D-gate-history (S4) in DECISIONS.md.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "event", "gate", "at"],
+  "properties": {
+    "schema": { "const": "sbf.gate-event/1" },
+    "event": { "enum": ["pass", "awaiting_disposition", "force", "revoke"] },
+    "gate": { "type": "string" },
+    "at": { "type": "string", "format": "date-time" },
+    "status": { "type": "string" },
+    "token": { "type": ["string", "null"] },
+    "forced": { "type": "boolean" },
+    "reason": { "type": ["string", "null"] }
+  }
+}

package/schemas/handles-plan.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:handles-plan:1",
+  "title": "backend-skeleton framework-neutral handles plan",
+  "description": "Validates the output of a handles provider's plan(). Top-level and resource objects both allow additionalProperties: true so each provider can carry its own extra fields (Java: service/fetchOperation; Python: publicModel/modelImport/fetchRoute/sessionDep) alongside the neutral subset the CLI renderer and dispatch layer consume. See D-handles-providers in DECISIONS.md.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schema", "provider", "module", "resources", "notes"],
+  "properties": {
+    "schema": { "const": "sbf.handles-plan/1" },
+    "provider": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "module": { "type": ["string", "null"] },
+    "resources": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["type", "table", "idField", "readPath", "requiredAuthority", "willGenerateResolver"],
+        "properties": {
+          "type": { "type": "string" },
+          "table": { "type": ["string", "null"] },
+          "idField": { "type": ["string", "null"] },
+          "readPath": { "type": ["string", "null"] },
+          "requiredAuthority": { "type": "string" },
+          "willGenerateResolver": { "type": "boolean" }
+        }
+      }
+    },
+    "notes": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/schemas/handles-provider.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:handles-provider:1",
+  "title": "backend-skeleton handles codegen provider descriptor",
+  "description": "Validates the JSON-shaped fields of the `provider` object a handles/providers/<id>.mjs module must export (plan/emit are functions, checked separately by handles/registry.mjs since a schema can't validate a function). Loaded at process start. See D-handles-providers in DECISIONS.md.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contract", "id", "title", "requiresCapabilities", "outputs"],
+  "properties": {
+    "contract": { "const": "sbf.handles-provider/1" },
+    "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "title": { "type": "string", "minLength": 1 },
+    "requiresCapabilities": {
+      "type": "array",
+      "items": { "enum": ["api.operations", "api.request-shape", "resource.fetch", "codegen.handles"] }
+    },
+    "outputs": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["spec"],
+      "properties": {
+        "spec": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/schemas/patch-approvals.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:patch-approvals:1",
+  "title": "backend-skeleton patch-strategy approvals (specs/<feature_id>/handles/patch-approvals.json)",
+  "description": "A3 (D-patch-strategy): written by `bskel handles patch approve`. Each entry is a specific {resource, field} pair, never a wildcard -- mirrors contract-resolution.schema.json's own no-wildcard-waiver precedent (A5). Only patch-wrapper/null-means-unchanged strategies can be approved (fetch-merge-submit/unsupported are never auto-generated, approving them would have no effect) -- enforced by `bskel handles patch approve` itself, not by this schema, so a hand-edited file with an unexpected strategy string still fails validation loudly rather than silently doing nothing.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "feature_id", "approvals"],
+  "properties": {
+    "schema": { "const": "sbf.patch-approvals/1" },
+    "feature_id": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" },
+    "approvals": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["resource", "field", "strategy", "reason", "at"],
+        "properties": {
+          "resource": { "type": "string" },
+          "field": { "type": "string" },
+          "strategy": { "enum": ["patch-wrapper", "null-means-unchanged"] },
+          "reason": { "type": "string" },
+          "at": { "type": "string", "format": "date-time" }
+        }
+      }
+    }
+  }
+}

package/schemas/scan-report.schema.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:scan-report:1",
+  "title": "backend-skeleton brownfield scan report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "terms", "adapter", "verdict", "related_modules", "collisions", "unknowns", "files_read"],
+  "properties": {
+    "schema": { "const": "sbf.scan-report/1" },
+    "feature_id": { "type": "string" },
+    "terms": { "type": "array", "items": { "type": "string" } },
+    "adapter": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "confidence": { "enum": ["high", "low"] },
+    "api_surface_source": { "type": "string" },
+    "verdict": { "enum": ["greenfield", "adjacent", "collision"] },
+    "path_prefix_signals": { "type": "array" },
+    "related_modules": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["module", "score"],
+        "properties": {
+          "module": { "type": "string" },
+          "score": { "type": "number" },
+          "controllers": { "type": "array" },
+          "entities": { "type": "array" },
+          "enums": { "type": "array" },
+          "dtos": { "type": "array", "items": { "type": "string" } },
+          "evidence": {
+            "description": "D-scanner-evidence: every {signal, term, value, weight, file, line} match that contributed to `score` -- capped per signal type AT COLLECTION TIME (not filtered afterward), so this array's size stays bounded regardless of repo size. See `capped_signals` for which signal types actually hit that cap.",
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["signal", "term", "value", "weight", "file", "line"],
+              "properties": {
+                "signal": { "enum": ["module_name", "controller_class", "controller_path", "endpoint_path", "endpoint_operation_id", "entity_table", "entity_class", "enum_name"] },
+                "term": { "type": "string" },
+                "value": { "type": ["string", "null"] },
+                "weight": { "type": "number" },
+                "file": { "type": ["string", "null"] },
+                "line": { "type": ["integer", "null"] }
+              }
+            }
+          },
+          "capped_signals": {
+            "description": "D-scanner-evidence: which signal types (a subset of `evidence[].signal`'s enum) had MORE raw matches than the per-signal cap -- named here once per module rather than recording every excess match individually, which is what kept `evidence` unbounded before this field existed.",
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    },
+    "collisions": { "type": "array" },
+    "unknowns": { "type": "array", "items": { "type": "string" } },
+    "files_read": {
+      "description": "S2 (D-gate-precision, continued): the adapter's own real read-set, repo-relative -- what lib/gate-definitions.mjs's `scan` gate re-derives and hashes for a precise staleness token instead of a repo-wide head_sha proxy. Always present (an adapter with nothing to scan yet, or one that predates this field, reports an empty array), never inferred from `related_modules` (which is filtered to score>0 and blind to a newly-added file that hasn't been re-scanned yet).",
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "db_schema": {
+      "description": "A4 (D-db-schema-plane): present only when `--db` was passed. `migrations` (Plane A, always local) and `live` (Plane C, present only with --database-url-env) are independent -- a repo can have one, the other, both, or (most repos, including the real oracle repo) neither.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["migrations", "live"],
+      "properties": {
+        "migrations": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["tool", "files", "tables"],
+          "properties": {
+            "tool": { "enum": ["flyway", "liquibase", "none"] },
+            "files": { "type": "array", "items": { "type": "string" } },
+            "tables": { "type": "array" }
+          }
+        },
+        "live": {
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "required": ["schema", "tables", "schema_hash"],
+          "properties": {
+            "schema": { "type": "string" },
+            "tables": { "type": "array" },
+            "schema_hash": { "type": "string" }
+          }
+        }
+      }
+    },
+    "disposition": {
+      "type": "object",
+      "properties": {
+        "mode": { "enum": ["reuse", "extend", "replace", "parallel"] },
+        "note": { "type": "string" },
+        "module": {
+          "description": "S2 (D-gate-precision, part 2): which related_modules[].module this feature disposed onto -- null for a greenfield verdict (no modules to choose from). Defaults to the top-scored module (matching contracts/emit.mjs's selectModule() default) when `scan disposition --module` wasn't passed explicitly. The `contract` gate's staleness token narrows to just this module's own files using this field.",
+          "type": ["string", "null"]
+        },
+        "at": { "type": "string", "format": "date-time" }
+      }
+    }
+  }
+}

package/schemas/stack-choice.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:stack-choice:1",
+  "title": "backend-skeleton stack catalog entry",
+  "description": "Validates a stack/catalog/<id>.yml file: what static, codegen-time artifacts a stack choice needs (files, .env.example entries, config checks) vs. what only exists once its bootstrap script actually runs.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "description", "static", "runtime"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "description": { "type": "string" },
+    "detect": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "files": { "type": "array", "items": { "type": "string" } },
+        "env_keys": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "static": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "files": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["path", "template"],
+            "properties": {
+              "path": { "type": "string" },
+              "template": { "type": "string" },
+              "mode": { "type": "string" }
+            }
+          }
+        },
+        "env_example": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["key", "doc"],
+            "properties": {
+              "key": { "type": "string" },
+              "required": { "type": "boolean" },
+              "secret": { "type": "boolean" },
+              "doc": { "type": "string" }
+            }
+          }
+        },
+        "config_check": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["target", "externalized_pattern", "note"],
+            "properties": {
+              "target": { "type": "string" },
+              "externalized_pattern": { "type": "string" },
+              "note": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "runtime": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["script", "produces"],
+      "properties": {
+        "script": { "type": "string" },
+        "requires": { "type": "array", "items": { "type": "string" } },
+        "readiness": {
+          "type": "object",
+          "properties": { "probe": { "type": "string" } }
+        },
+        "produces": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["key", "sink"],
+            "properties": {
+              "key": { "type": "string" },
+              "sink": { "enum": ["env"] },
+              "mode": { "enum": ["set", "append-unique"] }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/stack-record.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:stack-record:1",
+  "title": "backend-skeleton applied-stack runtime record",
+  "description": "Validates .sbf/stack.json, written by `bskel stack apply --apply` (bin/bskel.mjs's cmdStackApply). NOT the same schema as stack-choice.schema.json, which validates a stack/catalog/<id>.yml CATALOG ENTRY (an extension author's config) -- this validates the RUNTIME RECORD of which choice was applied and what it wrote, a distinct persistence boundary. See D-persistence-integrity (S5) in DECISIONS.md for why this schema didn't exist before.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "choice", "applied_files", "env_example_keys", "at"],
+  "properties": {
+    "schema": { "const": "sbf.stack/1" },
+    "choice": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "applied_files": {
+      "description": "S2: this choice's FULL file set in this repo (its desired state), not just what the most recent --apply happened to write -- see the S2 comment at this record's write site in bin/bskel.mjs.",
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "env_example_keys": { "type": "array", "items": { "type": "string" } },
+    "at": { "type": "string", "format": "date-time" }
+  }
+}

package/schemas/state.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:state:1",
+  "title": "backend-skeleton per-feature state",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "feature_id", "gates"],
+  "properties": {
+    "schema": { "const": "sbf.state/1" },
+    "feature_id": {
+      "type": "string",
+      "description": "a real feature_id, or the reserved repo-scope sentinel \"_repo\" used by repo-scoped gates (preflight, stack) -- see REPO_GATE_ID in lib/gate-definitions.mjs.",
+      "pattern": "^(_repo|[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*)$"
+    },
+    "feature_uid": { "type": "string", "format": "uuid" },
+    "gates": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["status", "token", "at"],
+        "properties": {
+          "status": {
+            "description": "S4: the only THREE statuses ever WRITTEN to disk (see lib/gates.mjs's passGate/awaitDispositionGate/revokeGate). `not_run`, `stale`, and `pass (forced)` are derived at READ time by requireGate() by recomputing the token from current inputs -- they are never stored, so they must not appear here.",
+            "enum": ["pass", "awaiting_disposition", "revoked"]
+          },
+          "token": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+          "at": {
+            "type": "string",
+            "description": "S5: deliberately NOT format:date-time. lib/gates.mjs's checkFreshness() already has its own dedicated, more lenient handling for an unparseable `at` (Date.parse + Number.isFinite -> STALE_REASON.INVALID_TIMESTAMP, a graceful fail-closed result, not a crash) -- see D-preflight-freshness (S3) and test/gates.test.mjs's \"missing or unparseable at timestamp\" test, which deliberately writes a non-ISO string to simulate hand-edited/corrupted state. Enforcing format:date-time here would turn that already-shipped, tested, deliberate behavior into a hard read-time crash instead."
+          },
+          "forced": { "type": "boolean", "description": "a forced gate is always stored as status:\"pass\" with this set true -- there is no separate \"pass (forced)\" value on disk; requireGate() only reports that string back at read time." },
+          "reason": { "type": "string", "description": "required when forced is true, or when status is \"revoked\" -- see lib/gates.mjs's forceGate/revokeGate (\"every bypass/revocation must be auditable\")." },
+          "evidence": { "type": "object" },
+          "inputs": {
+            "type": "object",
+            "description": "S2: the raw, pre-hash input set `token` was computed from, canonically key-sorted -- stored so a stale gate can report exactly WHICH input changed instead of only that the token moved (lib/gates.mjs's diffInputs()/explainStaleness()). Absent on records written before S2; requireGate() reports those as stale with stale_reason \"no_recorded_inputs\" rather than guessing."
+          }
+        }
+      }
+    }
+  }
+}