@mriekki/project-forge 4.12.0 → 4.13.1

package/assets/generated/core/core/skills/run/SKILL.md

@@ -8,47 +8,72 @@ disable-model-invocation: true
 
 # Run
 
-`/run` is the normal convenience entry point for starting the project locally. It resolves and delegates to repository-owned runtime commands rather than requiring the developer to remember framework-specific launch syntax.
+`/run` is the normal convenience entry point for starting the project locally. Core stays stack-neutral; the Project becomes deterministic by exposing a repository-owned local runtime command and runtime/persistence pairing once executable application topology exists. Follow `docs/process/LOCAL_DEVELOPMENT_COMMANDS.md` when present.
 
 ## Contract
 
-Invoking `/run` authorizes one bounded local start attempt for the requested target. It does not authorize setup, source edits, deployment, release publication, Production access, or persistent background services outside the repository's normal local-development contract.
+Invoking `/run` authorizes one bounded local start attempt for the requested target. It does not authorize setup, source edits, migrations, database reset/replacement, deployment, release publication, Production access, or persistent background services outside the repository's normal local-development contract.
 
-Resolve the local runtime command from current repository evidence in this order:
+Resolve the local runtime from current repository evidence in this order:
 
-1. an explicit repository-owned run/dev wrapper or documented command;
-2. an explicit package/task script whose purpose is local run/dev;
-3. an unambiguous ecosystem-native local entry point already present in the repository.
+1. an explicit developer-selected supported runtime/target, when one was supplied;
+2. the established Project-owned default local runtime and its associated persistence, including a project-owned local container/database when the repository defines that as the developer topology;
+3. an explicit repository-owned run/dev wrapper or documented command for that selected runtime;
+4. an explicit package/task script whose purpose is local run/dev;
+5. an unambiguous ecosystem-native local entry point already present in the repository, but only when the Project has not yet established a repository-owned runtime contract.
 
 Do not guess. If the repository has multiple independent runtimes and no documented default, require a target such as `/run web`, `/run api`, or `/run all`.
 
+For normal Feature Brief and Engineering Enabler development/validation, default to the established Project-owned local runtime and associated persistence unless the developer explicitly selects an alternative. Do not silently start a native process or use a separate checkout database merely because an ecosystem-native command is convenient.
+
+Once a repository-owned runtime command exists, treat it as authoritative for that runtime. If it is stale or fails because topology changed, report the contract problem; do not silently bypass it with another runtime/database.
+
 ## Preconditions
 
 Before starting:
 
 - identify repository root and current Git state;
 - inspect `PROJECT_BOOTSTRAP.json` and scaffold/readiness evidence when present;
+- resolve the exact selected runtime and, when applicable, the persistence instance it owns or uses;
 - verify the selected runtime entry point exists;
-- inspect any documented local ports/health endpoints;
+- inspect documented local ports, health endpoints, launch profiles, and transport/authentication requirements;
 - do not create an intentionally deferred scaffold merely to make `/run` succeed.
 
 If runtime source is intentionally deferred or absent, return `RUN NOT AVAILABLE` and identify the owning work item or missing marker when repository evidence provides it.
 
 If workstation tools or dependencies are missing, recommend `/setup` instead of silently installing them.
 
+### Persistence and schema readiness
+
+When the selected runtime requires persistence, inspect repository-owned non-mutating readiness evidence for the **exact selected persistence instance** before claiming functional readiness. This may include installed Project Forge/Deployment Kit status primitives, migration status commands, repository health/doctor commands, or other documented read-only checks.
+
+- If initialization or required schema is known to be missing/stale, do not automatically migrate, reset, delete, replace, or switch databases. Report `PERSISTENCE BLOCKED` and route to `/setup local` or the repository-owned repair workflow.
+- If the repository does not expose a safe way to establish schema compatibility, report `PERSISTENCE UNVERIFIED`. Do not turn a successful connection, process start, `/version`, or connection-only health check into an application-readiness claim.
+- If the application has no persistence requirement for the selected runtime, report persistence as `N/A`; do not invent a database gate.
+
+A stopped, absent, stale, or migration-pending Project-owned default container/database is a prerequisite problem, not permission to select a different runtime. An explicit developer selection may authorize a supported alternative within the existing `/run` boundary; inspect only that selected runtime and persistence.
+
+### Transport/authentication readiness
+
+Resolve documented transport prerequisites before choosing a launch profile. If normal authentication development requires HTTPS, secure cookies, or another repository-declared transport property, use the supported Project-owned profile/runtime when available or report the unresolved prerequisite. Do not disable secure-cookie policy, invent TLS/provider settings, or weaken authentication configuration to make `/run` succeed.
+
 ## Execution
 
-Start the process in an observable developer-controlled terminal/process surface. Do not hide a long-running application in an unexplained background process.
+Start the selected process/runtime in an observable developer-controlled terminal/process surface. Do not hide a long-running application in an unexplained background process.
 
-Report:
+Report these evidence dimensions separately:
 
-- target;
+- target and selected runtime identity;
 - resolved command identity;
 - process/startup result;
 - effective application release/build identity when the running application exposes it;
-- local URL/port or health evidence only when repository/runtime evidence establishes it;
+- persistence readiness: `READY`, `BLOCKED`, `UNVERIFIED`, or `N/A`;
+- local URL/port and transport evidence only when repository/runtime evidence establishes it;
+- functional checks actually performed and their result;
 - how to stop the process.
 
+Do not equate startup, artifact identity, `/version`, or connection-only health with successful user workflows. Do not claim login, OAuth callback/provider readiness, or another functional path was verified unless that exact path was exercised successfully.
+
 When `/run all` is explicitly supported, start only the repository-defined set of local components and make each process/endpoint visible.
 
 When the project implements `docs/process/APPLICATION_VERSIONING.md`, prefer runtime-observed version evidence over a source-file guess. Do not synthesize a build number or claim that a static source label proves the running artifact's identity.
@@ -57,7 +82,7 @@ When the project implements `docs/process/APPLICATION_VERSIONING.md`, prefer run
 
 `/run` may write a concise sanitized startup receipt under `.project-forge/logs/run/` following `docs/process/OPERATION_JOURNAL.md`.
 
-Record startup command identity, target, timestamps, startup/health result, observed application version/build identity, and endpoint when established. Do not duplicate or continuously capture unbounded application stdout/stderr into the Project Forge journal.
+Record selected runtime/persistence identity (without secrets), startup command identity, target, timestamps, process/startup result, persistence readiness, functional checks actually performed, observed application version/build identity, and endpoint when established. Do not duplicate or continuously capture unbounded application stdout/stderr into the Project Forge journal.
 
 ## Deployment boundary
 
@@ -66,10 +91,11 @@ Record startup command identity, target, timestamps, startup/health result, obse
 It must not:
 
 - mutate remote environments;
+- perform setup or migration writes implicitly;
 - publish images/packages/releases;
 - change deployment bindings;
 - infer Production configuration;
 - bump or rewrite release version state;
 - stage, commit, push, merge, or clean branches.
 
-A successful `/run` proves only that the requested local runtime started with the evidence observed in that session.
+A successful `/run` proves only the evidence dimensions actually observed for the selected local runtime in that session.

package/assets/generated/core/core/skills/start-work/SKILL.md

@@ -165,7 +165,11 @@ PRIMARY review subject is the final proposed implementation plan. Prefer:
 2. a durable plan document when one exists and is useful;
 3. otherwise the full substantive plan in the conversation.
 
-If a durable plan is a repository artifact and VS Code can invoke the Project Forge companion extension, use `projectForge.openReviewArtifact` with the exact workspace-relative path. If the host exposes a stronger native plan/review surface, use that instead.
+If a durable plan is a repository artifact, resolve its exact work-item-specific path from the current work-item authority/gate state before opening it. Do not select a global plan, another work item's artifact, or a focus-derived file.
+
+In VS Code, when the Project Forge companion review command/tool is available, request presentation of that exact artifact. Record the actual presentation outcome when the host reports one, including rendered Markdown vs editor fallback vs unavailable/failed. If the host exposes a stronger native plan/review surface, use that instead.
+
+If automatic opening is unavailable or fails, keep the gate usable: include the exact plan link/path inside the question and provide a deterministic manual fallback. For Markdown in VS Code on Windows, tell the human to open the exact linked file and press `Ctrl+Shift+V`.
 
 Before rendering the gate, state explicitly:
 
@@ -180,7 +184,9 @@ IMPLEMENTATION PLAN REVIEW REQUIRED
 
 Work item: <ID / key / concise change>
 Risk: <STANDARD | ELEVATED>
-Review subject: <native plan / exact plan path>
+Approval subject: final proposed implementation plan
+Primary artifact: <exact clickable work-item plan link/path | native plan surface>
+Presentation: <rendered Markdown opened | editor fallback opened | automatic opening unavailable/failed | native plan foregrounded>
 
 Plan covers:
 - approach
@@ -200,9 +206,11 @@ Implementation has NOT started.
 4. Stop [NO ACTION]
 ```
 
-When the host exposes structured choice UI, render the actions as a single-select control rather than a numbered menu while preserving the consequence labels. Do not preselect or infer `Approve plan and begin implementation` merely because the plan exists or the human invoked `/start-work`.
+The exact PRIMARY artifact link/path must be present in the approval question itself; do not rely on a link in earlier commentary. The artifact named in the gate must be the same artifact requested/opened for presentation.
+
+When the host exposes structured choice UI, render the actions as a single-select control rather than a numbered menu while preserving the consequence labels and the same work-item/artifact context in the question. Do not preselect or infer `Approve plan and begin implementation` merely because the plan exists, was opened, or the human invoked `/start-work`.
 
-Only option 1 (or equivalent explicit free-text authorization) authorizes substantive implementation. Options 2-4 do not.
+Only option 1 (or equivalent explicit free-text authorization) authorizes substantive implementation. Options 2-4 do not. Preview, navigation, cancellation, or a question asking where the plan is never counts as approval.
 
 ### Material plan changes after approval
 
@@ -222,10 +230,11 @@ APPROVED PLAN CHANGED
 
 Material change: ...
 Reason: ...
-Revised plan: ...
+Revised PRIMARY artifact: <exact revised plan link/path | native plan surface>
+Presentation: <actual presentation evidence>
 ```
 
-Foreground the revised PRIMARY plan review surface when supported, then require renewed plan approval. Do not silently continue implementation under stale authorization.
+Foreground the revised PRIMARY plan review surface when supported, then require renewed plan approval using the revised exact link/path inside the question. Do not silently continue implementation under stale authorization or reuse stale presentation evidence.
 
 ## 6. Working branch setup
 

package/assets/generated/core/tools/vscode_work_item_status/extension/README.md

@@ -1,6 +1,6 @@
 # Project Forge Work Item Status
 
-This optional local VS Code extension decorates Project Forge work-item folders in the Explorer from repository evidence and provides a read-only helper for Project Forge human-review surfaces.
+This optional local VS Code extension decorates Project Forge work-item folders in the Explorer from repository evidence and provides read-only helpers for Project Forge human-review surfaces.
 
 ## Work-item status
 
@@ -18,12 +18,16 @@ Project Forge workflows may use **Project Forge: Open Review Artifact** immediat
 
 The command accepts an exact workspace-relative repository artifact path when invoked programmatically. When run manually from the Command Palette without a path, it asks for the workspace-relative path.
 
+On VS Code hosts that support the Language Model Tool API, the extension also contributes the read-only `projectForge_openReviewArtifact` tool so an agent can request the same exact presentation operation without arbitrary command execution. Older supported VS Code hosts keep the command/manual fallback.
+
 Behavior:
 
-- Markdown files open in rendered Markdown Preview when available;
+- Markdown files request rendered Markdown Preview first;
+- when Markdown Preview is unavailable, the helper reports that fact and falls back to normal editor preview;
 - other repository artifacts open in the normal VS Code editor preview;
 - targets outside the currently open workspace are rejected;
-- missing or ambiguous multi-root targets are reported rather than guessed;
+- missing or ambiguous multi-root targets are reported rather than guessed from active editor focus;
+- the presentation result distinguishes the resolved URI, requested mode, actual opened mode, cancellation, and failure;
 - opening/previewing an artifact is read-only presentation and never records approval.
 
-Project Forge should foreground only the PRIMARY review subject automatically. Supporting CONTEXT and TRACEABILITY documents remain available without stealing focus unless the human chooses to open them.
+Project Forge should foreground only the exact PRIMARY review subject automatically. Supporting CONTEXT and TRACEABILITY documents remain available without stealing focus unless the human chooses to open them. The approval question itself must still identify and link the same artifact; a successful open is presentation evidence only.

package/assets/generated/core/tools/vscode_work_item_status/extension/extension.js

@@ -13,6 +13,7 @@ const ID_FROM_NAME = /^([A-Za-z][A-Za-z0-9]*-\d+)(?:-|$)/;
 const ID_FROM_BRANCH = /(?:^|\/)([A-Za-z][A-Za-z0-9]*-\d+)(?:-|\/|$)/i;
 const MARKER = /<!--\s*project-forge-work-item:\s*([A-Za-z][A-Za-z0-9]*-\d+)\s*-->/gi;
 const REFRESH_INTERVAL_MS = 120000;
+const REVIEW_TOOL_NAME = 'projectForge_openReviewArtifact';
 
 function normalizeId(value) {
   return value ? value.toUpperCase() : undefined;
@@ -242,32 +243,42 @@ async function resolveReviewUri(target) {
     throw new Error(`Review artifact was not found in the open workspace: ${requested}`);
   }
 
-  const activeEditor = vscode.window.activeTextEditor;
-  const activeFolder = activeEditor
-    ? vscode.workspace.getWorkspaceFolder(activeEditor.document.uri)
-    : undefined;
-  const activeMatch = activeFolder
-    ? matches.find((entry) => entry.folder.uri.fsPath === activeFolder.uri.fsPath)
-    : undefined;
-  if (activeMatch) {
-    return activeMatch.uri;
-  }
-
   throw new Error(`Review artifact path is ambiguous across workspace folders: ${requested}`);
 }
 
-async function openReviewArtifact(target) {
+function requestedReviewMode(uri) {
+  const extension = path.extname(uri.fsPath).toLowerCase();
+  return extension === '.md' || extension === '.markdown'
+    ? 'markdown-preview'
+    : 'editor-preview';
+}
+
+async function presentReviewArtifact(target, options = {}) {
+  const notify = options.notify !== false;
+  let uri;
   try {
-    const uri = await resolveReviewUri(target);
+    uri = await resolveReviewUri(target);
     if (!uri) {
-      return undefined;
+      return {
+        status: 'cancelled',
+        uri: null,
+        requestedMode: null,
+        openedMode: null,
+        message: 'No review artifact was selected.',
+      };
     }
 
-    const extension = path.extname(uri.fsPath).toLowerCase();
-    if (extension === '.md' || extension === '.markdown') {
+    const requestedMode = requestedReviewMode(uri);
+    if (requestedMode === 'markdown-preview') {
       try {
         await vscode.commands.executeCommand('markdown.showPreview', uri);
-        return uri.toString();
+        return {
+          status: 'opened',
+          uri: uri.toString(),
+          requestedMode,
+          openedMode: 'rendered-markdown',
+          message: 'Rendered Markdown preview opened.',
+        };
       } catch {
         // Fall back to the normal editor preview surface when Markdown preview is unavailable.
       }
@@ -277,11 +288,40 @@ async function openReviewArtifact(target) {
       preview: true,
       preserveFocus: false,
     });
-    return uri.toString();
+    return {
+      status: 'opened',
+      uri: uri.toString(),
+      requestedMode,
+      openedMode: 'editor-preview',
+      message: requestedMode === 'markdown-preview'
+        ? 'Rendered Markdown preview was unavailable; editor preview opened instead.'
+        : 'Editor preview opened.',
+    };
   } catch (error) {
     const message = error && error.message ? error.message : String(error);
-    await vscode.window.showWarningMessage(`Project Forge review artifact: ${message}`);
-    return undefined;
+    if (notify) {
+      await vscode.window.showWarningMessage(`Project Forge review artifact: ${message}`);
+    }
+    return {
+      status: 'failed',
+      uri: uri ? uri.toString() : null,
+      requestedMode: uri ? requestedReviewMode(uri) : null,
+      openedMode: null,
+      message,
+    };
+  }
+}
+
+async function openReviewArtifact(target) {
+  return presentReviewArtifact(target, { notify: true });
+}
+
+class OpenReviewArtifactTool {
+  async invoke(options) {
+    const result = await presentReviewArtifact(options && options.input, { notify: false });
+    return new vscode.LanguageModelToolResult([
+      new vscode.LanguageModelTextPart(JSON.stringify(result)),
+    ]);
   }
 }
 
@@ -373,6 +413,18 @@ function activate(context) {
   context.subscriptions.push(
     vscode.commands.registerCommand('projectForge.openReviewArtifact', openReviewArtifact),
   );
+
+  if (
+    vscode.lm &&
+    typeof vscode.lm.registerTool === 'function' &&
+    typeof vscode.LanguageModelToolResult === 'function' &&
+    typeof vscode.LanguageModelTextPart === 'function'
+  ) {
+    context.subscriptions.push(
+      vscode.lm.registerTool(REVIEW_TOOL_NAME, new OpenReviewArtifactTool()),
+    );
+  }
+
   context.subscriptions.push(
     vscode.window.onDidChangeWindowState((event) => {
       if (event.focused) {
@@ -406,4 +458,10 @@ function activate(context) {
 
 function deactivate() {}
 
-module.exports = { activate, deactivate, openReviewArtifact, resolveReviewUri };
+module.exports = {
+  activate,
+  deactivate,
+  openReviewArtifact,
+  presentReviewArtifact,
+  resolveReviewUri,
+};

package/assets/generated/core/tools/vscode_work_item_status/extension/package.json

@@ -2,7 +2,7 @@
   "name": "project-forge-work-item-status",
   "displayName": "Project Forge Work Item Status",
   "description": "Shows evidence-backed Project Forge work-item status badges and provides read-only review-surface helpers in VS Code.",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "publisher": "project-forge",
   "license": "UNLICENSED",
   "engines": {
@@ -19,7 +19,8 @@
   ],
   "activationEvents": [
     "workspaceContains:docs/work-items/*",
-    "onCommand:projectForge.openReviewArtifact"
+    "onCommand:projectForge.openReviewArtifact",
+    "onLanguageModelTool:projectForge_openReviewArtifact"
   ],
   "main": "./extension.js",
   "extensionKind": [
@@ -41,6 +42,29 @@
         "command": "projectForge.openReviewArtifact",
         "title": "Project Forge: Open Review Artifact"
       }
+    ],
+    "languageModelTools": [
+      {
+        "name": "projectForge_openReviewArtifact",
+        "displayName": "Open Project Forge Review Artifact",
+        "canBeReferencedInPrompt": true,
+        "toolReferenceName": "projectForgeReviewArtifact",
+        "userDescription": "Open an exact workspace review artifact using the safest read-only review surface available.",
+        "modelDescription": "Use immediately before a Project Forge artifact-based human approval gate when the exact review artifact path is already known. Opens only that exact workspace-contained file and returns structured presentation evidence. It never approves, edits, commits, or guesses an ambiguous target.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "path": {
+              "type": "string",
+              "description": "Exact workspace-relative or absolute workspace-contained path of the PRIMARY review artifact. Do not infer it from editor focus."
+            }
+          },
+          "required": [
+            "path"
+          ],
+          "additionalProperties": false
+        }
+      }
     ]
   }
 }

package/assets/generated/deployment/docs/RECOVERY_READINESS.md

@@ -0,0 +1,66 @@
+# Recovery Readiness Contract V1
+
+Project Forge distinguishes a verified database backup from verified application recovery. A successful SQLite backup proves only the database artifact created by the application's SQLite maintenance contract; it does not prove that every dependency required to recover authentication or the full application is available or usable.
+
+## Recovery states
+
+Reusable evidence must keep these concepts separate:
+
+1. `databaseBackupVerified` — the SQLite database backup operation completed successfully.
+2. `verifiedBackupScope` — currently `database` for SQLite backup evidence.
+3. `recoveryScopeDeclared` — the consumer supplied a strict, non-secret recovery declaration.
+4. `unresolvedRequiredDependencies` — required non-database dependencies that still need recovery-time verification.
+5. `authenticationPolicyVerified` — the selected authentication recovery policy has been dynamically verified after restore.
+6. `applicationRecoveryReady` — all required recovery dependencies and the selected policy have been verified for the restored application.
+
+Current SQLite backup/import/migration commands never set `applicationRecoveryReady` to true. Deployment Kit does not yet provide a general restore engine.
+
+## Recovery manifest
+
+`sqlite backup` and existing-database `sqlite migrate` may receive `--recovery-manifest <path>` pointing to UTF-8 JSON with exactly this schema:
+
+```json
+{
+  "schemaVersion": 1,
+  "authenticationPolicy": "invalidate-authentication",
+  "dependencies": [
+    {
+      "id": "data-protection-key-ring",
+      "type": "cryptographic-key-ring",
+      "required": true
+    }
+  ]
+}
+```
+
+`authenticationPolicy` may be `preserve-authentication`, `invalidate-authentication`, or `null`. Dependency IDs/types are non-secret identifiers only. Unknown fields fail closed. Do not put paths, keys, credentials, cookies, tokens, passwords, action links, provider secrets, or secret values in the manifest.
+
+The normalized manifest is fingerprinted deterministically and the privacy-safe declaration/readiness summary is included in SQLite evidence. Secret contents are neither archived nor printed by this contract. First-install migration, import, interrupted-import recovery, and rollback checking do not accept a recovery manifest in V1.
+
+## Authentication recovery policies
+
+`preserve-authentication` means a future recovery workflow must prove that required cryptographic/protector dependencies remain usable and that retaining historical authentication state is acceptable.
+
+`invalidate-authentication` means a future recovery workflow must prove that sessions and action links from historical state cannot authenticate or mutate accounts after recovery. Merely replacing a key ring is not sufficient evidence because password hashes, security stamps, sessions, token expiry/consumption, and similar state may also exist in the restored database.
+
+Neither policy is considered verified by a database backup alone.
+
+## Pre-traffic invariant
+
+A future restore operation must fail closed and keep the restored application unavailable to normal traffic until all required recovery dependencies and the selected authentication policy have been verified. Restore completion and database integrity must never be treated as equivalent to application recovery readiness.
+
+## Requirements
+
+- **PF-REC-001** — Database backup verification must never imply whole-application recovery readiness.
+- **PF-REC-002** — Consumers may declare non-database recovery dependencies without exposing secret values.
+- **PF-REC-003** — Required dependencies must be verified before application recovery readiness can pass.
+- **PF-REC-004** — Authentication-bearing consumers must select an explicit post-restore authentication policy when they want application recovery readiness.
+- **PF-REC-005** — Historical restore must remain unavailable to normal traffic until that policy is verified.
+- **PF-REC-006** — Incomplete or failed recovery evidence fails closed.
+- **PF-REC-007** — Existing SQLite-only consumers retain current database backup behavior and database-only success semantics.
+- **PF-REC-008** — Read-only planning/readiness inspection performs no restore, key manipulation, revocation, rotation, or other destructive action.
+- **PF-REC-009** — Dynamic recovery validation uses disposable fixtures and never logs secret material.
+
+## Non-scope
+
+This contract does not implement generic secret archival, provider-specific secret storage, key transport, key rotation, session/token mutation, or a general database/application restore workflow. Those require separate requirements, plan approval, implementation review, and release/adoption gates.

package/assets/generated/deployment/src/project_forge_deployment/recovery_scope.py

@@ -0,0 +1,116 @@
+"""Reusable recovery-scope declarations and non-secret readiness evidence."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from typing import Any
+
+from .errors import DeploymentKitError
+
+RECOVERY_SCHEMA_VERSION = 1
+AUTHENTICATION_POLICIES = {"preserve-authentication", "invalidate-authentication"}
+_ID_RE = re.compile(r"^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$")
+_ALLOWED_TOP = {"schemaVersion", "authenticationPolicy", "dependencies"}
+_ALLOWED_DEPENDENCY = {"id", "type", "required"}
+
+
+def _identifier(value: Any, field: str) -> str:
+    if not isinstance(value, str) or _ID_RE.fullmatch(value) is None:
+        raise DeploymentKitError(f"{field} must use lowercase letters, digits, dots, underscores, and internal hyphens.")
+    return value
+
+
+def normalize_recovery_scope(value: dict[str, Any] | None) -> dict[str, Any]:
+    """Normalize a strict, non-secret recovery declaration.
+
+    The declaration deliberately has no free-form values, paths, credentials, or
+    provider configuration. It describes recovery dependencies without storing
+    their contents or teaching generic persistence tooling how to archive them.
+    """
+    if value is None:
+        return {
+            "schemaVersion": RECOVERY_SCHEMA_VERSION,
+            "declared": False,
+            "authenticationPolicy": None,
+            "dependencies": [],
+            "manifestSha256": None,
+        }
+    if not isinstance(value, dict) or set(value) != _ALLOWED_TOP:
+        raise DeploymentKitError(
+            "Recovery manifest must contain exactly schemaVersion, authenticationPolicy, and dependencies."
+        )
+    if value["schemaVersion"] != RECOVERY_SCHEMA_VERSION:
+        raise DeploymentKitError(f"Recovery manifest schemaVersion must be {RECOVERY_SCHEMA_VERSION}.")
+    policy = value["authenticationPolicy"]
+    if policy is not None and policy not in AUTHENTICATION_POLICIES:
+        raise DeploymentKitError(
+            "authenticationPolicy must be preserve-authentication, invalidate-authentication, or null."
+        )
+    dependencies = value["dependencies"]
+    if not isinstance(dependencies, list):
+        raise DeploymentKitError("Recovery manifest dependencies must be an array.")
+    normalized: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for dependency in dependencies:
+        if not isinstance(dependency, dict) or set(dependency) != _ALLOWED_DEPENDENCY:
+            raise DeploymentKitError("Each recovery dependency must contain exactly id, type, and required.")
+        dependency_id = _identifier(dependency["id"], "Recovery dependency id")
+        dependency_type = _identifier(dependency["type"], "Recovery dependency type")
+        required = dependency["required"]
+        if not isinstance(required, bool):
+            raise DeploymentKitError("Recovery dependency required must be a boolean.")
+        if dependency_id in seen:
+            raise DeploymentKitError(f"Duplicate recovery dependency id: {dependency_id}")
+        seen.add(dependency_id)
+        normalized.append({"id": dependency_id, "type": dependency_type, "required": required})
+    normalized.sort(key=lambda item: item["id"])
+    canonical = {
+        "schemaVersion": RECOVERY_SCHEMA_VERSION,
+        "authenticationPolicy": policy,
+        "dependencies": normalized,
+    }
+    fingerprint = hashlib.sha256(
+        json.dumps(canonical, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).hexdigest()
+    return {
+        **canonical,
+        "declared": True,
+        "manifestSha256": fingerprint,
+    }
+
+
+def public_recovery_scope(scope: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "schemaVersion": scope["schemaVersion"],
+        "declared": scope["declared"],
+        "authenticationPolicy": scope["authenticationPolicy"],
+        "dependencies": [dict(item) for item in scope["dependencies"]],
+        "manifestSha256": scope["manifestSha256"],
+    }
+
+
+def recovery_readiness(scope: dict[str, Any], *, database_backup_verified: bool) -> dict[str, Any]:
+    unresolved = [item["id"] for item in scope["dependencies"] if item["required"]]
+    return {
+        "schemaVersion": RECOVERY_SCHEMA_VERSION,
+        "databaseBackupVerified": bool(database_backup_verified),
+        "verifiedBackupScope": "database" if database_backup_verified else None,
+        "recoveryScopeDeclared": scope["declared"],
+        "authenticationPolicy": scope["authenticationPolicy"],
+        "authenticationPolicyVerified": False if scope["authenticationPolicy"] is not None else None,
+        "unresolvedRequiredDependencies": unresolved,
+        "manifestSha256": scope["manifestSha256"],
+        "applicationRecoveryReady": False,
+        "readinessReason": "restore-policy-not-verified" if scope["declared"] else "recovery-scope-not-declared",
+    }
+
+
+def recovery_evidence(scope: dict[str, Any], *, database_backup_verified: bool) -> dict[str, Any]:
+    """Return the privacy-safe evidence payload persisted with a SQLite operation."""
+    readiness = recovery_readiness(scope, database_backup_verified=database_backup_verified)
+    return {
+        **readiness,
+        "dependencies": [dict(item) for item in scope["dependencies"]],
+    }