backend-skeleton 1.0.0 → 1.1.1

package/scanners/adapters/javascript-express.mjs

@@ -226,10 +226,40 @@ function resolveEsmImport(fromFile, specifier, suffixes) {
 	return null;
 }
 
-// `export default router;` -- which locally-declared mountable a file hands to whoever imports it.
-function defaultExportedMountable(text, mountables) {
-	const m = text.match(/export\s+default\s+([\w$]+)\s*;?/);
-	return m && mountables.has(m[1]) ? m[1] : null;
+// D-javascript-express-adapter (Update): found by the same shadow-validation-style audit that
+// closed D-module-attribution-base-package's own EXIT item for this adapter -- cross-file mount
+// resolution only ever recognized `export default router;`, a real but narrower limitation than
+// java-spring's own moduleOf() bug (endpoints still get FOUND either way, only their prefix goes
+// unresolved). A router handed off via a bare named export (`export { router };`) or an
+// export-prefixed declaration (`export const router = Router();`, ordinary and common) previously
+// had no path to being recognized as this file's "the" exported mountable at all.
+//
+// Three real ways a module hands a locally-declared mountable to whoever imports it -- `export
+// { router as r }` aliasing is deliberately NOT resolved, same restraint as this file's own
+// `Router as R` import-aliasing decision (D-javascript-express-adapter COST): a documented, narrow
+// limitation, not a silent guess at which local name an alias refers to.
+function exportedMountableName(text, mountables) {
+	const defaultMatch = text.match(/export\s+default\s+([\w$]+)\s*;?/);
+	if (defaultMatch && mountables.has(defaultMatch[1])) return defaultMatch[1];
+	const namedMatch = text.match(/export\s*\{\s*([\w$]+)\s*\}/);
+	if (namedMatch && mountables.has(namedMatch[1])) return namedMatch[1];
+	const exportedDeclMatch = text.match(/\bexport\s+(?:const|let|var)\s+([\w$]+)\s*=/);
+	if (exportedDeclMatch && mountables.has(exportedDeclMatch[1])) return exportedDeclMatch[1];
+	return null;
+}
+
+// `import target from '...'` (default) OR `import { target } from '...'` (named, unaliased) --
+// two real ways an imported mountable's LOCAL name reaches this file. `import { target as alias }`
+// is deliberately not resolved, same restraint as exportedMountableName's own aliasing decision
+// above -- a bare, unaliased single-name clause only, matching this file's existing default-import
+// regex's own narrow scope (never a general multi-specifier import-clause parser).
+function importSourceFor(text, target) {
+	const defaultImportRe = new RegExp(`import\\s+${target}\\s*(?:,\\s*\\{[^}]*\\})?\\s*from\\s*["']([^"']+)["']`);
+	const defaultMatch = text.match(defaultImportRe);
+	if (defaultMatch) return defaultMatch[1];
+	const namedImportRe = new RegExp(`import\\s*\\{\\s*${target}\\s*\\}\\s*from\\s*["']([^"']+)["']`);
+	const namedMatch = text.match(namedImportRe);
+	return namedMatch ? namedMatch[1] : null;
 }
 
 // Builds the mount graph over (file, variable) nodes. Two edge kinds, both from the same
@@ -261,13 +291,12 @@ function buildMountEdges(files, fileInfo, suffixes) {
 				edges.push({ from: nodeKey(file, fromVar), to: nodeKey(file, target), prefix: pathMatch[1] });
 				continue;
 			}
-			const importRe = new RegExp(`import\\s+${target}\\s*(?:,\\s*\\{[^}]*\\})?\\s*from\\s*["']([^"']+)["']`);
-			const importMatch = info.text.match(importRe);
-			if (!importMatch) continue;
-			const toFile = resolveEsmImport(file, importMatch[1], suffixes);
+			const importSource = importSourceFor(info.text, target);
+			if (!importSource) continue;
+			const toFile = resolveEsmImport(file, importSource, suffixes);
 			if (!toFile || !fileInfo.has(toFile)) continue;
 			const toInfo = fileInfo.get(toFile);
-			const toVar = defaultExportedMountable(toInfo.text, toInfo.mountables);
+			const toVar = exportedMountableName(toInfo.text, toInfo.mountables);
 			if (!toVar) continue;
 			edges.push({ from: nodeKey(file, fromVar), to: nodeKey(toFile, toVar), prefix: pathMatch[1] });
 		}
@@ -391,10 +420,14 @@ export const adapter = {
 	// walk), not how many capabilities it can offer. generic-grep is `low` because it has no module
 	// inference and no prefix resolution at all -- this adapter has both.
 	confidence: 'high',
-	// D-adapter-verification-basis: no real-world oracle at all, unlike every other real framework
-	// adapter -- the real target repository was deliberately never touched, and the committed
-	// synthetic fixture carries all of the regression weight. Named honestly, not hidden.
-	verificationBasis: 'synthetic-only',
+	// D-oracle-corpus-pinning: promoted from synthetic-only -- 3 real, pinned community repos
+	// now exist in test/fixtures/oracle-manifest.json (JeanCaicedo/employees-api-mysql,
+	// Serkanbyx/chat-app-backend, nekesam/helloworld), found via a genuine search effort that
+	// contradicted this adapter's own prior 'may be structurally unpromotable' hedge. The
+	// committed synthetic fixture still carries the exact-count regression weight; the real
+	// corpus is diagnostic/diversity coverage on top, same role every other adapter's real
+	// oracle plays.
+	verificationBasis: 'community-sample',
 	capabilities: {
 		// false: plain Express has no operationId concept at all. --openapi-file is the honest path
 		// forward for an app that has one; see CAPABILITY_SATISFIERS in scanners/capabilities.mjs.

package/scanners/adapters/python-fastapi.mjs

@@ -23,7 +23,8 @@ const EXCLUDE_GLOBS = ['!**/.venv/**', '!**/site-packages/**', '!**/node_modules
 // `fastapi==0.100.0`.
 const FASTAPI_DEP_RE = /(?:^|[\s"'[])fastapi(?:\[[^\]]*\])?(?:[\s"',\]=<>~!;]|$)/mi;
 
-const VERB_DECORATOR_RE = /@\w+\.(get|post|put|patch|delete)\s*\(/gi;
+const VERB_DECORATOR_RE = /@(\w+)\.(get|post|put|patch|delete)\s*\(/gi;
+const ROUTER_DECL_RE = /(\w+)\s*=\s*APIRouter\s*\(/g;
 const CLASS_RE = /^class\s+(\w+)\s*\(([^)]*)\)\s*:/gm;
 const INCLUDE_ROUTER_RE = /include_router\s*\(/g;
 
@@ -104,24 +105,42 @@ function capitalize(s) {
 // resolved against a global prefix applied elsewhere (e.g. `include_router(prefix=...)`) -- that
 // asymmetry is exactly what `pathPrefixSignals`/`unknowns` exists to flag, same role java-spring's
 // detectGlobalPathPrefixSignals plays for `configurePathMatch`/`context-path`.
-function extractBasePath(text) {
-	const m = text.match(/APIRouter\s*\(/);
-	if (!m) return '';
-	const openIdx = m.index + m[0].length - 1;
-	const closeIdx = matchBalancedParens(text, openIdx);
-	if (closeIdx === -1) return '';
-	const prefixMatch = text.slice(openIdx + 1, closeIdx).match(/prefix\s*=\s*["']([^"']*)["']/);
-	return prefixMatch ? prefixMatch[1] : '';
+//
+// D-fastapi-multi-router-per-file: a real dogfooding find against `polarsource/polar` (a 400+
+// route production FastAPI monorepo) -- 3 real files (`checkout/endpoints.py`,
+// `member/endpoints.py`, `auth/oauth2/router.py`) declare MORE THAN ONE `<var> = APIRouter(...)`
+// in the same file (e.g. member.py's `router = APIRouter(prefix="/members")` plus a second,
+// distinct `customer_members_router = APIRouter(prefix="/customers")` for a nested customer-scoped
+// resource). The single-basePath-per-file design used to always read only the FIRST `APIRouter(`
+// occurrence and apply it to every decorator in the file regardless of which router variable
+// actually decorates it -- silently discarding the second router's own real prefix. Returns
+// Map<varName, prefix> for every declared router in the file so each decorator can look up its
+// OWN router's prefix instead.
+function extractRouterPrefixes(text) {
+	const prefixes = new Map();
+	for (const m of text.matchAll(ROUTER_DECL_RE)) {
+		const openIdx = m.index + m[0].length - 1;
+		const closeIdx = matchBalancedParens(text, openIdx);
+		if (closeIdx === -1) continue;
+		const prefixMatch = text.slice(openIdx + 1, closeIdx).match(/prefix\s*=\s*["']([^"']*)["']/);
+		prefixes.set(m[1], prefixMatch ? prefixMatch[1] : '');
+	}
+	return prefixes;
 }
 
 // `operationId` is always null -- see the adapter's own `api.operations: false` and
 // D-fastapi-adapter in DECISIONS.md: FastAPI generates operation ids at request-handling time
 // (per-project, sometimes via a custom `generate_unique_id_function`), never pinned in source the
 // way `@Operation(operationId=...)` is for Java, so there is nothing honest to statically correlate.
+//
+// D-fastapi-multi-router-per-file: `routerVar` (the exact identifier before `.get`/`.post`/...) is
+// now captured per endpoint so the caller can resolve basePath per-router-variable rather than
+// once for the whole file -- see extractRouterPrefixes() above.
 function extractEndpoints(text) {
 	const endpoints = [];
 	for (const m of text.matchAll(VERB_DECORATOR_RE)) {
-		const verb = m[1].toUpperCase();
+		const routerVar = m[1];
+		const verb = m[2].toUpperCase();
 		const openIdx = m.index + m[0].length - 1;
 		const closeIdx = matchBalancedParens(text, openIdx);
 		if (closeIdx === -1) continue;
@@ -134,11 +153,19 @@ function extractEndpoints(text) {
 		const funcMatch = afterDecoratorRe.exec(text);
 		if (!funcMatch) continue;
 
-		endpoints.push({ verb, path: pathMatch[1], operationId: null, method: funcMatch[1], line: lineNumberAt(text, m.index) });
+		endpoints.push({ verb, path: pathMatch[1], operationId: null, method: funcMatch[1], routerVar, line: lineNumberAt(text, m.index) });
 	}
 	return endpoints;
 }
 
+// snake_case/mixed identifier -> PascalCase, e.g. "customer_members_router" -> "CustomerMembersRouter",
+// "inner_router" -> "InnerRouter". Only used for a NON-default router variable name (see
+// scanPythonFastApi below) -- the common single-router-per-file case keeps its existing
+// `${capitalize(moduleName)}Router` className exactly as before, byte-for-byte.
+function pascalCase(identifier) {
+	return identifier.split('_').filter(Boolean).map(capitalize).join('');
+}
+
 // SQLModel `class X(<bases>, table=True):` -- table name is the lowercased class name (SQLModel's
 // own default when no explicit `__tablename__` is declared; cross-checked against the real
 // oracle's own Alembic migration, `op.create_table("user", ...)`/`op.create_table("item", ...)`,
@@ -249,9 +276,10 @@ function extractIncludeRouterPrefixSignals(repoRoot, files) {
 	return signals;
 }
 
-// D-fastapi-adapter: paths are router-local (see extractBasePath); FastAPI generates operation ids
-// at runtime, never pinned in source -- see extractEndpoints. --openapi-file + --path-prefix is the
-// trustworthy path (contracts/openapi.mjs's existing, adapter-agnostic reconciliation).
+// D-fastapi-adapter: paths are router-local (see extractRouterPrefixes); FastAPI generates
+// operation ids at runtime, never pinned in source -- see extractEndpoints. --openapi-file +
+// --path-prefix is the trustworthy path (contracts/openapi.mjs's existing, adapter-agnostic
+// reconciliation).
 const API_SURFACE_SOURCE = 'router-local paths only (this scan does not resolve a global prefix applied via ' +
 	'include_router(prefix=...) beyond a simple literal/single-variable lookup -- see unknowns below if one ' +
 	'was found) -- FastAPI generates operation ids at request-handling time (per-project, sometimes via a ' +
@@ -277,10 +305,27 @@ export function scanPythonFastApi(repoRoot, projectRoot) {
 			// login.py, which declares `APIRouter(tags=["login"])` with no prefix at all, so a
 			// prefix-derived name fails on a real file while the filename stem works for every one.
 			const moduleName = path.basename(file, '.py');
-			const basePath = extractBasePath(text);
-			const endpoints = extractEndpoints(text).map((ep) => ({ ...ep, path: joinPath(basePath, ep.path) }));
-			if (endpoints.length > 0) {
-				moduleEntry(moduleName).controllers.push({ className: `${capitalize(moduleName)}Router`, basePath, operationIds: [], endpoints, file });
+			const routerPrefixes = extractRouterPrefixes(text);
+			const rawEndpoints = extractEndpoints(text);
+
+			// D-fastapi-multi-router-per-file: group by the router variable each decorator actually
+			// belongs to (not the file as a whole) -- a decorator on a router variable this file never
+			// itself declares (e.g. imported from elsewhere, or a same-file `include_router()` alias)
+			// falls back to '' rather than guessing, same as the pre-fix single-router behavior.
+			const byRouterVar = new Map();
+			for (const ep of rawEndpoints) {
+				if (!byRouterVar.has(ep.routerVar)) byRouterVar.set(ep.routerVar, []);
+				byRouterVar.get(ep.routerVar).push(ep);
+			}
+
+			for (const [routerVar, eps] of byRouterVar) {
+				const basePath = routerPrefixes.get(routerVar) ?? '';
+				const endpoints = eps.map((ep) => ({ verb: ep.verb, path: joinPath(basePath, ep.path), operationId: ep.operationId, method: ep.method, line: ep.line }));
+				// the common case (single router per file, conventionally named "router") keeps the
+				// existing className exactly as before -- only a second/other-named router variable
+				// gets a distinguishing className derived from its own identifier.
+				const className = routerVar === 'router' ? `${capitalize(moduleName)}Router` : `${pascalCase(routerVar)}`;
+				moduleEntry(moduleName).controllers.push({ className, basePath, operationIds: [], endpoints, file });
 			}
 		}
 

package/scanners/adapters/typescript-express.mjs

@@ -41,6 +41,17 @@ const ENTITY_CLASS_RE = /@Entity\s*\(\s*(?:["'`]([^"'`]*)["'`])?\s*\)\s*\n?\s*ex
 // exported symbol -- same file-level granularity java's own DTO tracking already settled for.
 const DTO_DIR_SEGMENT = `${path.sep}dto${path.sep}`;
 
+// D-module-attribution-base-package (Update): found by the same shadow-validation pass that fixed
+// java-spring's own moduleOf() -- a real project not using a `dto/` folder at all (flat `CreateUserDto.ts` files, or
+// NestJS's own common `create-user.dto.ts` naming) had every DTO silently invisible, the same class
+// of single-convention overfit, just on a narrower surface (DTO tracking only, not module/entity/
+// controller extraction). This does NOT reopen the CONTENT-detection problem the comment above
+// explicitly rejected (interface/type/class-validator/Zod/undecorated class all have different
+// shapes) -- it's an independent, NAME-only signal: the file's own basename ends in "dto"
+// (case-insensitive), the same near-definitional marker this file's own entity-matching step below
+// already leans on for MATCHING. Catches both `CreateUserDto.ts` and `create-user.dto.ts`.
+const DTO_NAME_SUFFIX_RE = /dto$/i;
+
 // Two independent signals required, mirroring java-spring's "build file AND src layout" /
 // python-fastapi's "dependency declared AND source-confirmed" combined bar: (a) package.json
 // declares express, (b) at least one .ts file actually imports Router from 'express' and calls
@@ -78,6 +89,20 @@ function listTypeScriptFiles(projectRoot) {
 // of `router.use('/literal', subRouter)` mount edges from a graph root down to the leaf file. This
 // extracts just the LOCAL endpoints (verb/path/handler/line) with an EMPTY prefix -- the mount-tree
 // walk in scanTypeScriptExpress() below joins the real prefix chain afterward.
+//
+// D-typescript-express-inline-handlers: an inline function expression (`router.get('/x', async
+// (req, res) => {...})`) is a DIFFERENT shape from a bare-identifier handler reference
+// (`router.get('/x', show)`) -- confirmed live, dogfooding against a real, popular repo
+// (gothinkster/node-express-realworld-example-app, 3,796 real GitHub stars): ALL 19 of its real
+// route registrations use this inline form, and the bare-identifier-only gate this comment used to
+// describe found ZERO of them (verdict: greenfield on a repo with a real, complete REST API).
+// `method: null` (not a synthesized/guessed name) marks this case -- there is no export to
+// correlate an inline handler to, and `handles/providers/typescript-express/plan.mjs`'s own
+// `resolveHandlerFile()` already has a real, tested `null`-propagates-to-"resolver not generated"
+// path for exactly this "handler correlates to nothing" case (see its own Update note in
+// DECISIONS.md) -- this is NOT a new failure mode, just a new, real way to reach the existing one.
+const INLINE_HANDLER_RE = /^(?:async\s+)?(?:\([^)]*\)|[$\w]+)\s*(?::[^=]*)?=>|^(?:async\s+)?function\b/;
+
 function extractEndpoints(text) {
 	const endpoints = [];
 	for (const m of text.matchAll(VERB_CALL_RE)) {
@@ -91,13 +116,14 @@ function extractEndpoints(text) {
 
 		const args = splitTopLevelArgs(argsText);
 		const lastArg = args[args.length - 1]?.trim();
-		// A bare identifier only -- an inline arrow-function handler has no name to correlate to a
-		// controller file, so it's skipped rather than guessed at (same discipline as FastAPI's own
-		// "no path literal -> skip").
 		const handlerMatch = lastArg?.match(/^(\w+)$/);
-		if (!handlerMatch) continue;
+		const isInlineHandler = !handlerMatch && lastArg && INLINE_HANDLER_RE.test(lastArg);
+		// Neither a bare identifier nor a recognizable inline function expression (e.g. a member
+		// expression like `controller.show`, or something built dynamically) -- skip rather than
+		// guess, same discipline as the missing-path-literal case just above.
+		if (!handlerMatch && !isInlineHandler) continue;
 
-		endpoints.push({ verb, path: pathMatch[1], operationId: null, method: handlerMatch[1], line: lineNumberAt(text, m.index) });
+		endpoints.push({ verb, path: pathMatch[1], operationId: null, method: handlerMatch ? handlerMatch[1] : null, line: lineNumberAt(text, m.index) });
 	}
 	return endpoints;
 }
@@ -251,8 +277,8 @@ export function scanTypeScriptExpress(repoRoot, projectRoot) {
 				moduleEntry(moduleName).controllers.push({ className, basePath: prefix, operationIds: [], endpoints, file });
 			}
 		}
-		if (file.includes(DTO_DIR_SEGMENT)) {
-			allDtos.push({ className: path.basename(file, '.ts'), file }); // no `line` -- path-based, no content parsed
+		if (file.includes(DTO_DIR_SEGMENT) || DTO_NAME_SUFFIX_RE.test(path.basename(file, '.ts'))) {
+			allDtos.push({ className: path.basename(file, '.ts'), file }); // no `line` -- path/name-based, no content parsed
 		}
 		allEntities.push(...extractTableEntities(text, file));
 	}

package/schemas/feature-contract.schema.json

@@ -36,16 +36,16 @@
           "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.",
+            "description": "A2: the operation's request body projected from a real OpenAPI 3.1 document -- see contracts/openapi.mjs's inlineSchema(). Fully inlined (no $ref) EXCEPT at a genuinely self-referential component (D-openapi-cyclic-refs), where a $ref/$defs pair is used instead -- see this schema's own top-level $defs when present. 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.",
+            "description": "A3: all documented 2xx application/json response schemas for this operation, fully inlined (no $ref) EXCEPT at a genuinely self-referential component (D-openapi-cyclic-refs, $ref/$defs used instead); 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.",
+            "description": "A3: all documented 4xx/5xx application/json response schemas for this operation, fully inlined (no $ref) EXCEPT at a genuinely self-referential component (D-openapi-cyclic-refs, $ref/$defs used instead); an anyOf union when 2+ distinct shapes are documented. Present only when matched/adopted AND at least one resolved.",
             "type": "object"
           },
           "sourceParameters": {

package/schemas/handles-plan.schema.json

@@ -20,6 +20,8 @@
           "type": { "type": "string" },
           "table": { "type": ["string", "null"] },
           "idField": { "type": ["string", "null"] },
+          "idFieldType": { "type": ["string", "null"], "description": "D-write-safety-phase1 (item 4a): java-spring only -- the primary key's declared Java type (e.g. 'UUID', 'Integer'). null when it couldn't be determined at all (not the same as a confirmed non-UUID type)." },
+          "idFieldIsUuid": { "type": ["boolean", "null"], "description": "D-write-safety-phase1 (item 4a): mirrors typescript-express's own already-established field of the same name. false means a resolver is structurally impossible for this entity (the handles subsystem is UUID-addressable only), independent of whether a service file can be found." },
           "readPath": { "type": ["string", "null"] },
           "requiredAuthority": { "type": "string" },
           "requiredAuthorityForPatch": { "type": "string", "description": "O5 (D-resolver-authorization-action-aware): java-spring only -- derived independently from the entity's UPDATE endpoint, not copied from requiredAuthority (which is fetch/recover's own value)." },

package/schemas/oracle-manifest.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:oracle-manifest:1",
+  "title": "backend-skeleton scanner-adapter verification-corpus manifest",
+  "description": "ROADMAP.md Phase 5b (D-oracle-corpus-pinning): the committed, human-readable record of real, third-party repos pinned to a real commit SHA per scanner adapter, driven by scripts/shadow-validation-smoke.mjs --manifest. Loaded at scripts/shadow-validation-smoke.mjs run time, not by the CLI itself -- this is a test/verification-only artifact, never read by bin/bskel.mjs.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contract", "adapters"],
+  "properties": {
+    "contract": { "const": "sbf.oracle-manifest/1" },
+    "adapters": {
+      "type": "object",
+      "propertyNames": {
+        "enum": ["java-spring", "python-fastapi", "typescript-express", "javascript-express", "generic-grep"]
+      },
+      "additionalProperties": {
+        "type": "array",
+        "minItems": 1,
+        "items": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "repo", "terms", "note"],
+          "properties": {
+            "id": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9-]*$",
+              "description": "Short, unique-within-this-adapter identifier for this manifest entry (e.g. 'spring-petclinic') -- used in report output, never sent to git/GitHub."
+            },
+            "owner": {
+              "type": ["string", "null"],
+              "description": "null means \"repo\" is used as-is as a literal clone URL/local path (matches scripts/shadow-validation-smoke.mjs's own parseRepoSpec literal form) -- ONLY for local, non-network test fixtures (test/shadow-validation-cli.test.mjs); every real corpus entry in this file names a real owner."
+            },
+            "repo": { "type": "string", "minLength": 1 },
+            "ref": {
+              "type": ["string", "null"],
+              "pattern": "^([0-9a-f]{40})?$",
+              "description": "A real, pinned commit SHA -- ROADMAP.md Phase 5b's own 'pin refs' requirement. null is permitted only for the local-fixture literal-owner form above (no meaningful \"pin\" for a throwaway local bare repo). Never a branch/tag name here (scripts/shadow-validation-smoke.mjs's own DEFAULT_REPOS/CLI-spec forms still accept branch names for quick manual use; this committed manifest does not)."
+            },
+            "path": {
+              "type": ["string", "null"],
+              "description": "Subdirectory within the clone to scope every bskel invocation to (relative, no leading/trailing slash) -- null/absent means the clone root. Needed for monorepos where the actual backend lives under a subdirectory (e.g. polarsource/polar's 'server')."
+            },
+            "terms": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "string", "minLength": 1 }
+            },
+            "note": {
+              "type": "string",
+              "minLength": 1,
+              "description": "One-line, human-readable justification for why this repo is in the corpus (what real coverage it adds, or what real diagnostic gap it's expected to surface) -- see DECISIONS.md's D-oracle-corpus-pinning for the full record."
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/stack-record.schema.json

@@ -15,6 +15,11 @@
       "items": { "type": "string" }
     },
     "env_example_keys": { "type": "array", "items": { "type": "string" } },
-    "at": { "type": "string", "format": "date-time" }
+    "at": { "type": "string", "format": "date-time" },
+    "file_hashes": {
+      "description": "D-write-safety-phase0 (item 2): additive, optional (absent on a record written before this existed -- planApply() treats a missing entry as no prior provenance, same as classifyFile()'s own no-manifest-entry fallback). sha256 of what `stack apply --apply` itself last wrote to each path in applied_files, keyed by that same relative path -- gives planApply() a preimage to check a hand-edit against, instead of only comparing to the current fresh render.",
+      "type": "object",
+      "additionalProperties": { "type": "string" }
+    }
   }
 }

package/stack/apply.mjs

@@ -6,6 +6,13 @@ import Ajv2020 from 'ajv/dist/2020.js';
 // P2b (D-greenfield-parameters): was a private `renderTemplate(templatePath, vars)` here, moved to
 // lib/template.mjs unchanged once `new/fastapi.mjs` became its second real consumer.
 import { renderTemplateFile } from '../lib/template.mjs';
+// D-write-safety-phase0 (item 2): reusing the exact same provenance-based classification and
+// git-recoverability check the handles write path already established, rather than inventing a
+// second one for this write path.
+import { classifyFile } from '../lib/handles-manifest.mjs';
+import { isDirtyOrUntracked } from '../handles/_engine.mjs';
+import { sha256String, readJsonIfExists } from '../lib/fsutil.mjs';
+import { sbfPath } from '../lib/paths.mjs';
 
 const STACK_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const SCHEMAS_ROOT = path.join(STACK_ROOT, '..', 'schemas');
@@ -84,19 +91,31 @@ export function planApply(repoRoot, entry, { port = 8080 } = {}) {
 	// crossed the stated boundary).
 	plan.alreadyDetected = (entry.detect?.files ?? []).some((f) => fs.existsSync(path.join(repoRoot, f)));
 
+	// D-write-safety-phase0 (item 2): `file_hashes` (additive, schemas/stack-record.schema.json) is
+	// what `stack apply` itself last wrote to each path -- absent on a record from before this
+	// existed, or if `stack apply` never ran. classifyFile()'s own no-manifest-entry fallback
+	// (content-comparison only) covers that case exactly the way handles emit's first-ever run does.
+	const priorRecord = readJsonIfExists(sbfPath(repoRoot, 'stack.json'));
+	const priorHashes = priorRecord?.file_hashes ?? {};
+
 	for (const f of entry.static?.files ?? []) {
 		const templatePath = path.join(STACK_ROOT, f.template);
 		assertContained(STACK_ROOT, templatePath, 'catalog template path');
 		const targetPath = path.join(repoRoot, f.path);
 		assertContained(repoRoot, targetPath, 'catalog target path');
 		const rendered = renderTemplateFile(templatePath, { PORT: port });
-		const exists = fs.existsSync(targetPath);
-		const unchanged = exists && fs.readFileSync(targetPath, 'utf8') === rendered;
+		const diskContent = fs.existsSync(targetPath) ? fs.readFileSync(targetPath, 'utf8') : null;
+		const exists = diskContent !== null;
+		const diskHash = exists ? sha256String(diskContent) : null;
+		const freshRenderHash = sha256String(rendered);
+		const matchesPristineRender = exists && diskContent === rendered;
+		const action = classifyFile({ exists, diskHash, manifestEntryHash: priorHashes[f.path] ?? null, freshRenderHash, matchesPristineRender });
 		plan.files.push({
 			path: f.path,
 			mode: f.mode ?? null,
-			action: !exists ? 'create' : (unchanged ? 'unchanged' : 'update'),
+			action,
 			content: rendered,
+			contentHash: freshRenderHash,
 		});
 	}
 
@@ -133,18 +152,40 @@ export function planApply(repoRoot, entry, { port = 8080 } = {}) {
 // API supports this), config_check could gain an `apply` action -- not built now because the
 // real target (Team-IZ-Backend) doesn't need it (already externalized), so there's no concrete
 // case to validate a patcher against yet.
-export function applyPlan(repoRoot, plan) {
+// D-write-safety-phase0 (item 2): `force` mirrors handles emit's own `--force` gate exactly -- a
+// `conflict` file (diverged from what `stack apply` itself last wrote) is refused outright without
+// it, and even with it is refused if not git-recoverable (uncommitted/untracked), so a --force
+// overwrite is only ever reversible. The `--reason` a real overwrite requires is a CLI-layer
+// concern (validated in cmdStackApply, mirroring cmdContractWaive/handles emit's identical
+// pattern) -- applyPlan() itself has nothing to do with an audit string it never persists. Returns
+// `fileHashes` (sha256 of what was ACTUALLY written this run) so the caller can persist it into
+// `.sbf/stack.json`'s new `file_hashes` field -- unchanged/adopt-unchanged files are simply absent
+// here, so the caller must merge onto the PRIOR record's file_hashes, not replace it wholesale.
+export function applyPlan(repoRoot, plan, { force = false } = {}) {
 	const written = [];
+	const conflicts = [];
+	const fileHashes = {};
 	for (const f of plan.files) {
-		if (f.action === 'unchanged') continue;
+		if (f.action === 'unchanged' || f.action === 'adopt-unchanged') continue;
 		const targetPath = path.join(repoRoot, f.path);
 		// Re-asserted here too (planApply already checked it) -- applyPlan must not assume it's
 		// only ever called with a plan it just generated for the same repoRoot.
 		assertContained(repoRoot, targetPath, 'catalog target path');
+		if (f.action === 'conflict') {
+			if (!force) {
+				conflicts.push({ path: f.path, reason: 'diverged from the last content `bskel stack apply` generated -- see notes for remediation' });
+				continue;
+			}
+			if (isDirtyOrUntracked(repoRoot, targetPath)) {
+				conflicts.push({ path: f.path, reason: 'refusing --force: this file has uncommitted/untracked changes -- commit or stash it first so the overwrite is recoverable' });
+				continue;
+			}
+		}
 		fs.mkdirSync(path.dirname(targetPath), { recursive: true });
 		fs.writeFileSync(targetPath, f.content);
 		if (f.mode) fs.chmodSync(targetPath, Number.parseInt(f.mode, 8));
 		written.push(f.path);
+		fileHashes[f.path] = f.contentHash;
 	}
 
 	const toAppend = plan.envExampleActions.filter((a) => a.action === 'append');
@@ -158,5 +199,5 @@ export function applyPlan(repoRoot, plan) {
 		written.push('.env.example');
 	}
 
-	return written;
+	return { written, conflicts, fileHashes };
 }