@foggy-projects/deepseek-harness-plugin 0.4.0-beta.5 → 0.4.0-beta.6

package/README.md

@@ -8,7 +8,7 @@ only when the user selects **Initialize Foggy**.
 ## Local beta installation
 
 ```powershell
-dsh plugin --profile web add --workspace-root ./foggy-projects-deepseek-harness-plugin-0.4.0-beta.5.tgz
+dsh plugin --profile web add --workspace-root ./foggy-projects-deepseek-harness-plugin-0.4.0-beta.6.tgz
 ```
 
 Restart `dsh web`, open Settings → Plugins → Foggy Data Analysis, and initialize
@@ -23,8 +23,9 @@ dsh plugin --profile web add --workspace-root @foggy-projects/deepseek-harness-p
 For development, `FOGGY_ASSET_CACHE_DIRS` can contain platform-delimited verified
 asset-cache directories. It is not required for a normal install.
 
-Database credentials are deliberately outside the ordinary DSH settings
-document. The database and semantic-layer wizard is the next Bundle milestone.
+Database credentials remain outside the ordinary DSH settings document. The
+bundled onboarding Skill drives datasource discovery, semantic drafting,
+checkpointed publication, and bounded read-only query verification.
 
 ## Native Skill and workspace contract
 
@@ -34,6 +35,11 @@ are available in every DSH workspace without copying or symlinking `.agents`.
 The current session `cwd` remains the workspace boundary for semantic drafts and
 evidence.
 
+Opaque CLI profiles default to the private persistent
+`<dataRoot>/cli-profiles` directory. Composite onboarding commands are
+idempotent: unchanged completed phases are resumed rather than re-adding a
+datasource or re-registering a published bundle.
+
 CLI, Launcher, the analysis Skill, install state, and Runtime state live in the
 user-level Foggy component directories. The managed CLI is intentionally isolated
 and does not need to be on `PATH`. **Re-download / Repair** verifies the global

package/lib/client.js

@@ -68,6 +68,7 @@ window.__ModuleLoader__.load({
       roots: '本地目录',
       installRoot: '组件目录',
       dataRoot: '数据目录',
+      profileStore: 'CLI Profile',
       runtimeUrl: 'Runtime 地址',
       nextTitle: '后续配置',
       nextCopy: 'Skills 已通过 DeepSeek Harness 原生注册表提供给所有工作区；每个会话直接使用自己的工作目录。Runtime 启动成功后，将继续进入数据库连接与语义层向导。',
@@ -116,6 +117,7 @@ window.__ModuleLoader__.load({
       roots: 'Local directories',
       installRoot: 'Components',
       dataRoot: 'Data',
+      profileStore: 'CLI profiles',
       runtimeUrl: 'Runtime URL',
       nextTitle: 'Next configuration',
       nextCopy: 'Skills are provided to every workspace through the native DeepSeek Harness registry, and each session uses its own working directory. After Runtime starts, the database connection and semantic-layer wizard comes next.',
@@ -288,6 +290,7 @@ window.__ModuleLoader__.load({
           jsxs('dl', { children: [
             jsx('dt', { children: t('installRoot') }), jsx('dd', { children: status.roots.installRoot }),
             jsx('dt', { children: t('dataRoot') }), jsx('dd', { children: status.roots.dataRoot }),
+            jsx('dt', { children: t('profileStore') }), jsx('dd', { children: status.roots.profileStore }),
             status.runtimeUrl ? jsx('dt', { children: t('runtimeUrl') }) : null,
             status.runtimeUrl ? jsx('dd', { children: status.runtimeUrl }) : null,
           ] }),

package/lib/index.js

@@ -20,17 +20,20 @@ function defaultRoots() {
     return {
       installRoot: join(base, 'Foggy', 'DeepSeekHarness'),
       dataRoot: join(base, 'Foggy', 'DeepSeekHarnessData'),
+      profileStore: process.env.FOGGY_RUNTIME_PROFILE_STORE || join(base, 'Foggy', 'DeepSeekHarnessData', 'cli-profiles'),
     }
   }
   const home = process.env.HOME
   if (!home) throw new Error('HOME is not set')
+  const dataRoot = process.env.XDG_STATE_HOME
+    ? join(process.env.XDG_STATE_HOME, 'foggy', 'deepseek-harness')
+    : join(home, '.local', 'state', 'foggy', 'deepseek-harness')
   return {
     installRoot: process.env.XDG_DATA_HOME
       ? join(process.env.XDG_DATA_HOME, 'foggy', 'deepseek-harness')
       : join(home, '.local', 'share', 'foggy', 'deepseek-harness'),
-    dataRoot: process.env.XDG_STATE_HOME
-      ? join(process.env.XDG_STATE_HOME, 'foggy', 'deepseek-harness')
-      : join(home, '.local', 'state', 'foggy', 'deepseek-harness'),
+    dataRoot,
+    profileStore: process.env.FOGGY_RUNTIME_PROFILE_STORE || join(dataRoot, 'cli-profiles'),
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foggy-projects/deepseek-harness-plugin",
-  "version": "0.4.0-beta.5",
+  "version": "0.4.0-beta.6",
   "description": "Foggy Java data analysis engine integration for DeepSeek Harness",
   "type": "module",
   "main": "./lib/index.js",
@@ -55,6 +55,6 @@
   },
   "scripts": {
     "check": "node --check lib/index.js && node --check lib/skill-provider.js && node --check lib/client.js && node --check lib/typert.js && node --check lib/remote.js",
-    "test": "node --test test/package.test.js"
+    "test": "node --test test/package.test.js && python test/onboarding_unit.py"
   }
 }

package/skills/foggy-deepseek-onboarding/SKILL.md

@@ -24,6 +24,12 @@ copy this Skill into the current workspace.
   analysis Skill is missing or invalid, ask the user to open the Foggy plugin settings and use
   **Re-download / Repair**. Repair restores the global managed analysis Skill and invalidates the
   native DSH Skill catalog. Reinstall or upgrade the plugin itself to restore this bundled Skill.
+- Treat the current DSH session workspace as the authoritative `projectRoot` for the whole onboarding
+  run. Do not redirect semantic drafts or contracts to a different repository merely because another
+  Skill or example was found there. Place non-secret contracts below
+  `<projectRoot>/.foggy/onboarding-contracts/<profile>/`, drafts below
+  `<projectRoot>/.foggy/onboarding-drafts/<profile>/`, and published files below the approved
+  project-relative `modelsDir`.
 
 ## Mandatory orchestration boundary
 
@@ -46,6 +52,9 @@ For every new-database onboarding session, this Skill is the orchestration autho
 - Never read query-execution evidence back into the conversation. Report only validation state,
   execution state, row count, and evidence path; do not report row values or generated SQL containing
   business literals.
+- Prefer one composite command per approval boundary. Do not inspect this Skill's Python implementation
+  or the CLI package source during a normal run; use the documented command contract and inspect code
+  only after a structured wrapper error requires troubleshooting.
 
 ## Boundaries
 
@@ -70,10 +79,12 @@ For every new-database onboarding session, this Skill is the orchestration autho
 4. Load `foggy-ai-analysis` from the native DSH Skill registry. Do not require a workspace copy.
 5. For a new business database, read [references/onboarding-workflow.md](references/onboarding-workflow.md)
    and prefer its two composite `onboard-datasource-run` / `onboard-semantic-run` commands. Require the
-   trusted operator to create the private CLI profile outside Harness. Accept only the opaque profile
+   trusted operator to create the private CLI profile outside Harness. Unless the operator explicitly
+   overrides it, use the persistent profile store reported by the wrapper under the Foggy data root
+   (`<dataRoot>/cli-profiles`), never `/tmp`. Accept only the opaque profile
    ID, exact revision, datasource name/type, and namespace; never request JDBC URL, username,
    password, or password environment-variable name in Harness.
-6. After schema discovery, use `foggy-ai-analysis` only to author TM/QM files in a separate project-local
+6. After schema discovery, use `foggy-ai-analysis` only to author TM/QM files in the standard project-local
    draft directory. Register, validate, publish, and verify them through this Skill's wrapper using the deterministic commands in
    [references/onboarding-workflow.md](references/onboarding-workflow.md). Do not publish, prune, replace
    a bundle, or execute a business-data query without the matching explicit flag and user approval.
@@ -98,5 +109,10 @@ In DeepSeek Harness, do not expand the composite onboarding commands back into t
 operations. This order documents what the wrapper enforces internally and becomes a direct CLI workflow
 only after onboarding is complete.
 
+Composite commands are checkpointed and idempotent: a retry skips completed datasource, validation,
+publication, and verification phases when the approved contract and draft digest are unchanged. Fix a
+query payload in place and rerun the same semantic composite command; do not remove a successfully
+published bundle merely to recover from a later query-validation failure.
+
 Keep user business data separate from the sales-drop SQLite demo. Prefer a read-only database account,
 opaque CLI profile references, and bounded query limits.

package/skills/foggy-deepseek-onboarding/assets/versions.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "foggy-deepseek-onboarding-versions/v1",
-  "packageVersion": "0.4.0-beta.5",
+  "packageVersion": "0.4.0-beta.6",
   "validatedAt": "2026-09-01",
   "components": {
     "deepseekHarness": {

package/skills/foggy-deepseek-onboarding/references/onboarding-workflow.md

@@ -23,6 +23,16 @@ to paste a password and do not put a JDBC URL, username, password environment-va
 line, logs, or evidence. For non-SQLite databases, ask the user to set the named environment variable
 before Runtime starts so the Java process inherits it. Recommend a read-only database account.
 
+Use the current DSH session workspace as `projectRoot`. Store approved non-secret contracts at
+`.foggy/onboarding-contracts/<profile>/`, semantic drafts at `.foggy/onboarding-drafts/<profile>/`, and
+command evidence at `.foggy/onboarding-command-evidence/<profile>/`. Do not split these files across the
+session workspace and a separate example repository. The wrapper rejects a query payload outside the
+recorded project root before any semantic validation or publication mutation occurs.
+
+The wrapper defaults `FOGGY_RUNTIME_PROFILE_STORE` to the private persistent directory
+`<dataRoot>/cli-profiles`. An explicit operator-provided value still wins. Do not use `/tmp` for a profile
+that must survive a WSL or Harness restart.
+
 Treat every user-supplied identifier and bound as immutable input: profile, datasource, namespace,
 models directory, bundle name, TM/QM name, query fields, and limit. Do not swap in demo names, add
 fields, raise the limit, or introduce replacement flags. If one of these inputs is missing, pause for
@@ -53,6 +63,13 @@ onboard-semantic-run --semantic-plan <approved-json> --query-payload <approved-j
 Include an approval flag only after the user approves that exact action. Without it, the composite
 command stops after the corresponding dry-run and returns `phaseStatus=awaiting-...-approval`.
 
+Both composite commands are resumable. When the approved contract is unchanged, they skip completed
+checkpoints instead of re-adding an existing datasource, revalidating an already published draft, or
+registering the same bundle twice. If query validation fails after publication, correct the project-local
+payload and rerun `onboard-semantic-run`; it resumes at query verification and leaves the active bundle in
+place. A same-name datasource is accepted idempotently only when its public name and database type match
+the approved plan; otherwise replacement still requires explicit approval.
+
 The granular commands below remain available for manual troubleshooting and resumption. Do not expand
 the composite commands into this list during a normal Harness turn.
 
@@ -111,6 +128,11 @@ requires an integer `limit` from 1 through 100. The first `semantic-verify` call
 validates the query; only `--execute` reads business data. Full results stay in evidence and the command
 returns only counts and paths.
 
+Before the first semantic mutation, the composite command checks that the query payload is inside
+`projectRoot`, has a bounded limit, and targets a query model declared in the approved semantic plan.
+After publication, `semantic-verify` always describes the live model before validation. If a field is
+rejected, update the payload from those described names and rerun the same composite command.
+
 Do not open, summarize, or quote `query-execute.json` or the Runtime's generated SQL after execution.
 The conversational result may contain only `queryValidated`, `queryExecuted`, `rowCount`, the model
 name, and the evidence path. A successful direct CLI command is not proof that onboarding completed;

package/skills/foggy-deepseek-onboarding/scripts/onboarding.py

@@ -448,6 +448,33 @@ def onboarding_state_path(data_root: Path, profile: str) -> Path:
     return data_root / "onboarding" / "profiles" / f"{safe_profile(profile)}.json"
 
 
+def configure_profile_store(data_root: Path, *, create: bool = True) -> Path:
+    """Keep opaque CLI profiles in the persistent, private Foggy data root by default."""
+    configured = os.environ.get("FOGGY_RUNTIME_PROFILE_STORE")
+    destination = normalized(configured) if configured else data_root / "cli-profiles"
+    if not configured:
+        os.environ["FOGGY_RUNTIME_PROFILE_STORE"] = str(destination)
+    if create:
+        destination.mkdir(parents=True, exist_ok=True)
+        if os.name != "nt":
+            destination.chmod(0o700)
+    return destination
+
+
+def resolve_profile_name(data_root: Path, requested: str | None) -> str:
+    if requested:
+        return safe_profile(requested)
+    profiles_dir = data_root / "onboarding" / "profiles"
+    candidates = sorted(path.stem for path in profiles_dir.glob("*.json") if PROFILE_PATTERN.fullmatch(path.stem))
+    if len(candidates) == 1:
+        return candidates[0]
+    if not candidates:
+        return "default"
+    raise OnboardingError(
+        "Multiple onboarding profiles exist; pass --profile explicitly: " + ", ".join(candidates)
+    )
+
+
 def read_onboarding_state(data_root: Path, profile: str, required: bool = True) -> dict | None:
     path = onboarding_state_path(data_root, profile)
     if not path.is_file():
@@ -802,10 +829,12 @@ def install_command(args: argparse.Namespace) -> dict:
     assert_managed_root(data_root, "Data root")
     if install_root == data_root:
         raise OnboardingError("Install root and data root must be different")
+    profile_store = normalized(os.environ.get("FOGGY_RUNTIME_PROFILE_STORE") or data_root / "cli-profiles")
     plan = {
         "schemaVersion": "foggy-deepseek-onboarding-plan/v1",
         "installRoot": str(install_root),
         "dataRoot": str(data_root),
+        "profileStore": str(profile_store),
         "workspaceMode": "dsh-session-cwd",
         "versions": {name: value.get("version") for name, value in components.items()},
         "operations": ["install isolated CLI", "verify Launcher assets", "install global analysis Skill", "write install state"],
@@ -813,6 +842,7 @@ def install_command(args: argparse.Namespace) -> dict:
     }
     if args.dry_run:
         return {"success": True, "dryRun": True, "plan": plan}
+    profile_store = configure_profile_store(data_root)
     progress = ProgressReporter(
         getattr(args, "progress_file", None),
         getattr(args, "operation_id", None),
@@ -945,6 +975,7 @@ def install_command(args: argparse.Namespace) -> dict:
         "packageVersion": versions["packageVersion"],
         "installRoot": str(install_root),
         "dataRoot": str(data_root),
+        "profileStore": str(profile_store),
         "workspaceMode": "dsh-session-cwd",
         "cli": {"version": cli_component["version"], "command": str(cli_command), "mode": cli_mode},
         "launcher": {"version": components["launcher"]["version"], "path": str(launcher_dir)},
@@ -1163,6 +1194,7 @@ def onboarding_context(args: argparse.Namespace, require_runtime: bool = False)
     install_state = read_install_state(install_root)
     data_root = normalized(args.data_root or install_state["dataRoot"])
     assert_managed_root(data_root, "Data root")
+    configure_profile_store(data_root, create=False)
     runtime_state_path = data_root / "runtime-state.json"
     runtime_state = read_json_object(runtime_state_path, "Runtime state") if runtime_state_path.is_file() else None
     if runtime_state and runtime_state.get("schemaVersion") != RUNTIME_STATE_SCHEMA:
@@ -1222,6 +1254,28 @@ def require_opaque_profile_cli(install_state: dict) -> None:
         )
 
 
+def datasource_entries(payload: dict) -> list[dict]:
+    for item in nested_data_objects(payload):
+        entries = item.get("datasources")
+        if isinstance(entries, list):
+            return [entry for entry in entries if isinstance(entry, dict)]
+    return []
+
+
+def matching_datasource(payload: dict, connection: dict) -> dict | None:
+    expected_name = connection["name"]
+    expected_type = connection["type"].lower()
+    if expected_type == "postgresql":
+        expected_type = "postgres"
+    for entry in datasource_entries(payload):
+        entry_type = str(entry.get("type", "")).lower()
+        if entry_type == "postgresql":
+            entry_type = "postgres"
+        if entry.get("name") == expected_name and entry_type == expected_type:
+            return entry
+    return None
+
+
 def onboarding_plan_command(args: argparse.Namespace) -> dict:
     install_root, install_state, data_root, runtime_state = onboarding_context(args, require_runtime=False)
     profile = safe_profile(args.profile)
@@ -1283,7 +1337,9 @@ def onboarding_plan_command(args: argparse.Namespace) -> dict:
 
 def require_profile(args: argparse.Namespace, require_runtime: bool = False) -> tuple[dict, dict, Path, dict | None]:
     _install_root, install_state, data_root, runtime_state = onboarding_context(args, require_runtime=require_runtime)
-    state = read_onboarding_state(data_root, safe_profile(args.profile))
+    profile = resolve_profile_name(data_root, getattr(args, "profile", None))
+    args.profile = profile
+    state = read_onboarding_state(data_root, profile)
     if normalized(state["installRoot"]) != normalized(install_state["installRoot"]):
         raise OnboardingError("Onboarding profile belongs to a different install root")
     return state, install_state, data_root, runtime_state
@@ -1329,10 +1385,31 @@ def datasource_configure_command(args: argparse.Namespace) -> dict:
         label = "datasources add"
     if args.replace:
         command.append("--replace")
-    result = redact_connection_material(
-        cli_json(install_state, runtime_state, connection["namespace"], command, label)
-    )
-    mark_step(state, "datasourceConfigured", "completed", replace=args.replace)
+    already_present = False
+    try:
+        result = redact_connection_material(
+            cli_json(install_state, runtime_state, connection["namespace"], command, label)
+        )
+    except OnboardingError as exc:
+        if "DATASOURCE_ALREADY_EXISTS" not in str(exc):
+            raise
+        listed = cli_json(
+            install_state, runtime_state, connection["namespace"], ["datasources", "list"], "datasources list"
+        )
+        existing = matching_datasource(listed, connection)
+        if existing is None:
+            raise OnboardingError(
+                f"Datasource {connection['name']} already exists but its public type does not match the approved plan; "
+                "do not replace it without explicit approval"
+            ) from exc
+        already_present = True
+        result = {
+            "success": True,
+            "idempotent": True,
+            "status": "already-present",
+            "dataSource": redact_connection_material(existing),
+        }
+    mark_step(state, "datasourceConfigured", "completed", replace=args.replace, alreadyPresent=already_present)
     path = write_onboarding_state(data_root, state)
     return {
         "success": True,
@@ -1340,6 +1417,7 @@ def datasource_configure_command(args: argparse.Namespace) -> dict:
         "profile": state["profile"],
         "statePath": str(path),
         "dataSource": connection["name"],
+        "alreadyPresent": already_present,
         "runtime": result,
         "next": "run datasource-verify; add --bind to approve namespace binding",
         "productionReady": False,
@@ -1798,7 +1876,16 @@ def semantic_verify_command(args: argparse.Namespace) -> dict:
     )
     atomic_json(evidence_dir / "query-execute.json", executed)
     row_count = response_row_count(executed)
-    mark_step(state, "semanticVerified", "completed", queryModel=query_model, queryValidated=True, queryExecuted=True)
+    mark_step(
+        state,
+        "semanticVerified",
+        "completed",
+        queryModel=query_model,
+        queryValidated=True,
+        queryExecuted=True,
+        rowCount=row_count,
+        queryPayloadDigest=sha256(payload_path),
+    )
     state.setdefault("artifacts", {})["semanticVerifyEvidence"] = str(evidence_dir)
     path = write_onboarding_state(data_root, state)
     return {
@@ -1818,14 +1905,15 @@ def semantic_verify_command(args: argparse.Namespace) -> dict:
 
 
 def next_onboarding_action(state: dict) -> dict:
+    profile_flag = f" --profile {state['profile']}"
     ordered = [
-        ("datasourceConfigured", "datasource-configure --apply"),
-        ("datasourceVerified", "datasource-verify --bind"),
-        ("schemaDiscovered", "schema-discover"),
-        ("semanticDrafted", "semantic-draft --semantic-plan <json>"),
-        ("semanticValidated", "semantic-validate --apply"),
-        ("semanticPublished", "semantic-publish --apply"),
-        ("semanticVerified", "semantic-verify --query-payload <json> --execute"),
+        ("datasourceConfigured", f"datasource-configure{profile_flag} --apply"),
+        ("datasourceVerified", f"datasource-verify{profile_flag} --bind"),
+        ("schemaDiscovered", f"schema-discover{profile_flag}"),
+        ("semanticDrafted", f"semantic-draft{profile_flag} --semantic-plan <json>"),
+        ("semanticValidated", f"semantic-validate{profile_flag} --apply"),
+        ("semanticPublished", f"semantic-publish{profile_flag} --apply"),
+        ("semanticVerified", f"semantic-verify{profile_flag} --query-payload <json> --execute"),
     ]
     for name, command in ordered:
         current = state.get("steps", {}).get(name, {})
@@ -1838,7 +1926,7 @@ def next_onboarding_action(state: dict) -> dict:
                     "instruction": "Inspect semantic publish evidence and repair refresh before any republish attempt.",
                 }
             if name == "semanticValidated" and current.get("status") == "failed":
-                command = "repair TM/QM, then semantic-draft --semantic-plan <json>"
+                command = f"repair TM/QM, then semantic-draft{profile_flag} --semantic-plan <json>"
             return {"step": name, "command": command, "status": current.get("status", "pending")}
     return {"step": None, "command": None, "status": "completed"}
 
@@ -1883,6 +1971,21 @@ def save_composite_result(evidence_dir: Path, name: str, payload: dict, files: l
     files.append(str(path))
 
 
+def resumed_phase(profile: str, phase: str, **values: object) -> dict:
+    return {
+        "success": True,
+        "schemaVersion": "foggy-deepseek-onboarding-resumed/v1",
+        "profile": profile,
+        "phase": phase,
+        "resumed": True,
+        **values,
+    }
+
+
+def step_completed(state: dict, name: str) -> bool:
+    return state.get("steps", {}).get(name, {}).get("status") == "completed"
+
+
 def datasource_run_command(args: argparse.Namespace) -> dict:
     _install_root, install_state, data_root, _runtime_state = onboarding_context(args, require_runtime=True)
     project_root = normalized(args.project_root or Path.cwd())
@@ -1902,6 +2005,11 @@ def datasource_run_command(args: argparse.Namespace) -> dict:
     if existing:
         if existing.get("connection") != requested_connection:
             raise OnboardingError("Existing onboarding profile does not match the requested connection plan")
+        if normalized(existing.get("projectRoot", "")) != project_root:
+            raise OnboardingError(
+                "Existing onboarding profile belongs to a different projectRoot; resume from that DSH workspace "
+                "or choose a new profile name"
+            )
         plan_result = {
             "success": True,
             "schemaVersion": "foggy-deepseek-onboarding-plan-result/v1",
@@ -1921,59 +2029,81 @@ def datasource_run_command(args: argparse.Namespace) -> dict:
             replace_plan=False,
         ))
     save_composite_result(evidence_dir, "01-plan.json", plan_result, files)
+    state = read_onboarding_state(data_root, profile)
 
-    configure_dry = datasource_configure_command(argparse.Namespace(
-        install_root=args.install_root, data_root=args.data_root, profile=profile, apply=False, replace=False,
-    ))
-    save_composite_result(evidence_dir, "02-datasource-dry.json", configure_dry, files)
-    if not args.approve_configure:
-        return {
-            "success": True,
-            "schemaVersion": "foggy-deepseek-datasource-run/v1",
-            "profile": profile,
-            "phaseStatus": "awaiting-configure-approval",
-            "evidenceDir": str(evidence_dir),
-            "evidenceFiles": files,
-            "next": "rerun with --approve-configure after the datasource mutation is approved",
-            "productionReady": False,
-        }
-
-    configured = datasource_configure_command(argparse.Namespace(
-        install_root=args.install_root, data_root=args.data_root, profile=profile, apply=True, replace=False,
-    ))
-    save_composite_result(evidence_dir, "03-datasource-apply.json", configured, files)
-    tested = datasource_verify_command(argparse.Namespace(
-        install_root=args.install_root, data_root=args.data_root, profile=profile, bind=False,
-    ))
-    save_composite_result(evidence_dir, "04-datasource-test.json", tested, files)
-    if not args.approve_bind:
-        return {
-            "success": True,
-            "schemaVersion": "foggy-deepseek-datasource-run/v1",
-            "profile": profile,
-            "phaseStatus": "awaiting-bind-approval",
-            "evidenceDir": str(evidence_dir),
-            "evidenceFiles": files,
-            "next": "rerun with --approve-configure --approve-bind after namespace binding is approved",
-            "productionReady": False,
-        }
+    if step_completed(state, "datasourceConfigured"):
+        configured = resumed_phase(profile, "datasourceConfigured")
+        save_composite_result(evidence_dir, "02-datasource-dry.json", configured, files)
+        save_composite_result(evidence_dir, "03-datasource-apply.json", configured, files)
+    else:
+        configure_dry = datasource_configure_command(argparse.Namespace(
+            install_root=args.install_root, data_root=args.data_root, profile=profile, apply=False, replace=False,
+        ))
+        save_composite_result(evidence_dir, "02-datasource-dry.json", configure_dry, files)
+        if not args.approve_configure:
+            return {
+                "success": True,
+                "schemaVersion": "foggy-deepseek-datasource-run/v1",
+                "profile": profile,
+                "phaseStatus": "awaiting-configure-approval",
+                "evidenceDir": str(evidence_dir),
+                "evidenceFiles": files,
+                "next": "rerun with --approve-configure after the datasource mutation is approved",
+                "productionReady": False,
+            }
+        configured = datasource_configure_command(argparse.Namespace(
+            install_root=args.install_root, data_root=args.data_root, profile=profile, apply=True, replace=False,
+        ))
+        save_composite_result(evidence_dir, "03-datasource-apply.json", configured, files)
+        state = read_onboarding_state(data_root, profile)
 
-    bound = datasource_verify_command(argparse.Namespace(
-        install_root=args.install_root, data_root=args.data_root, profile=profile, bind=True,
-    ))
-    save_composite_result(evidence_dir, "05-datasource-bind.json", bound, files)
-    discovered = schema_discover_command(argparse.Namespace(
-        install_root=args.install_root,
-        data_root=args.data_root,
-        profile=profile,
-        schema=args.schema,
-        pattern=args.pattern,
-        table=args.table,
-        max_tables=args.max_tables,
-        list_only=False,
-        no_views=args.no_views,
-        include_indexes=args.include_indexes,
-    ))
+    if step_completed(state, "datasourceVerified"):
+        bound = resumed_phase(profile, "datasourceVerified")
+        save_composite_result(evidence_dir, "04-datasource-test.json", bound, files)
+        save_composite_result(evidence_dir, "05-datasource-bind.json", bound, files)
+    else:
+        tested = datasource_verify_command(argparse.Namespace(
+            install_root=args.install_root, data_root=args.data_root, profile=profile, bind=False,
+        ))
+        save_composite_result(evidence_dir, "04-datasource-test.json", tested, files)
+        if not args.approve_bind:
+            return {
+                "success": True,
+                "schemaVersion": "foggy-deepseek-datasource-run/v1",
+                "profile": profile,
+                "phaseStatus": "awaiting-bind-approval",
+                "evidenceDir": str(evidence_dir),
+                "evidenceFiles": files,
+                "next": "rerun with --approve-configure --approve-bind after namespace binding is approved",
+                "productionReady": False,
+            }
+        bound = datasource_verify_command(argparse.Namespace(
+            install_root=args.install_root, data_root=args.data_root, profile=profile, bind=True,
+        ))
+        save_composite_result(evidence_dir, "05-datasource-bind.json", bound, files)
+        state = read_onboarding_state(data_root, profile)
+
+    if step_completed(state, "schemaDiscovered"):
+        schema_step = state["steps"]["schemaDiscovered"]
+        discovered = resumed_phase(
+            profile,
+            "schemaDiscovered",
+            selectedCount=schema_step.get("selectedCount", 0),
+            artifactPath=state.get("artifacts", {}).get("schemaDiscovery"),
+        )
+    else:
+        discovered = schema_discover_command(argparse.Namespace(
+            install_root=args.install_root,
+            data_root=args.data_root,
+            profile=profile,
+            schema=args.schema,
+            pattern=args.pattern,
+            table=args.table,
+            max_tables=args.max_tables,
+            list_only=False,
+            no_views=args.no_views,
+            include_indexes=args.include_indexes,
+        ))
     save_composite_result(evidence_dir, "06-schema.json", discovered, files)
     return {
         "success": True,
@@ -1989,6 +2119,29 @@ def datasource_run_command(args: argparse.Namespace) -> dict:
     }
 
 
+def semantic_plan_snapshot(state: dict, plan: dict) -> tuple[Path, dict, bool]:
+    project_root = normalized(state["projectRoot"])
+    draft_dir = normalized(project_root / plan["draftDir"])
+    if not is_child(draft_dir, project_root) or draft_dir == project_root:
+        raise OnboardingError("draftDir must stay inside projectRoot and cannot equal it")
+    manifest = semantic_manifest(draft_dir)
+    semantic = state.get("semantic", {})
+    registered = semantic.get("draftManifest") or {}
+    matches = bool(
+        step_completed(state, "semanticDrafted")
+        and normalized(semantic.get("draftDir", draft_dir)) == draft_dir
+        and semantic.get("bundleName") == plan["bundleName"]
+        and semantic.get("queryModels") == plan["queryModels"]
+        and registered.get("digest") == manifest["digest"]
+    )
+    return draft_dir, manifest, matches
+
+
+def published_digest_matches(state: dict, digest: str) -> bool:
+    published = state.get("steps", {}).get("semanticPublished", {})
+    return published.get("status") == "completed" and published.get("digest") == digest
+
+
 def semantic_run_command(args: argparse.Namespace) -> dict:
     approved_plan = validate_semantic_plan(read_json_object(normalized(args.semantic_plan), "Semantic plan"))
     if not approved_plan.get("profile"):
@@ -2000,6 +2153,17 @@ def semantic_run_command(args: argparse.Namespace) -> dict:
     profile_args.profile = profile
     state, _install_state, _data_root, _runtime_state = require_profile(profile_args, require_runtime=True)
     project_root = normalized(state["projectRoot"])
+    payload_path = normalized(args.query_payload)
+    if not is_child(payload_path, project_root):
+        raise OnboardingError(
+            "Query payload must stay inside projectRoot; place contracts under .foggy/onboarding-contracts before approval"
+        )
+    bounded_query_payload(payload_path)
+    declared_query_model = args.query_model or (approved_plan["queryModels"][0] if len(approved_plan["queryModels"]) == 1 else None)
+    if not declared_query_model:
+        raise OnboardingError("--query-model is required when the semantic plan declares multiple query models")
+    if declared_query_model not in approved_plan["queryModels"]:
+        raise OnboardingError("--query-model must be declared in semanticPlan.queryModels")
     contract_evidence = approved_plan.get("evidenceDir")
     if contract_evidence and args.evidence_dir:
         if normalized(project_root / contract_evidence) != normalized(args.evidence_dir):
@@ -2007,78 +2171,141 @@ def semantic_run_command(args: argparse.Namespace) -> dict:
     evidence_dir = composite_evidence_dir(project_root, profile, str(project_root / contract_evidence) if contract_evidence else args.evidence_dir)
     files: list[str] = []
 
-    drafted = semantic_draft_command(argparse.Namespace(
-        install_root=args.install_root,
-        data_root=args.data_root,
-        profile=profile,
-        semantic_plan=args.semantic_plan,
-    ))
+    _draft_dir, manifest, draft_matches = semantic_plan_snapshot(state, approved_plan)
+    published_matches = published_digest_matches(state, manifest["digest"])
+    if draft_matches or published_matches:
+        drafted = resumed_phase(profile, "semanticDrafted", digest=manifest["digest"])
+    else:
+        drafted = semantic_draft_command(argparse.Namespace(
+            install_root=args.install_root,
+            data_root=args.data_root,
+            profile=profile,
+            semantic_plan=args.semantic_plan,
+        ))
+        state = read_onboarding_state(normalized(state["dataRoot"]), profile)
+        manifest = state["semantic"]["draftManifest"]
     save_composite_result(evidence_dir, "07-semantic-draft.json", drafted, files)
-    validate_dry = semantic_validate_command(argparse.Namespace(
-        install_root=args.install_root,
-        data_root=args.data_root,
-        profile=profile,
-        apply=False,
-        include_stack_trace=False,
-    ))
-    save_composite_result(evidence_dir, "08-semantic-validate-dry.json", validate_dry, files)
-    if not args.approve_validate:
-        return {
-            "success": True,
-            "schemaVersion": "foggy-deepseek-semantic-run/v1",
-            "profile": profile,
-            "phaseStatus": "awaiting-validate-approval",
-            "evidenceDir": str(evidence_dir),
-            "evidenceFiles": files,
-            "next": "rerun with --approve-validate after the validation catalog mutation is approved",
-            "productionReady": False,
-        }
-
-    validated = semantic_validate_command(argparse.Namespace(
-        install_root=args.install_root,
-        data_root=args.data_root,
-        profile=profile,
-        apply=True,
-        include_stack_trace=False,
-    ))
+    state = read_onboarding_state(normalized(state["dataRoot"]), profile)
+    validation_step = state.get("steps", {}).get("semanticValidated", {})
+    published_matches = published_digest_matches(state, manifest["digest"])
+    validation_matches = validation_step.get("status") == "completed" and validation_step.get("digest") == manifest["digest"]
+    if validation_matches or published_matches:
+        if published_matches and not validation_matches:
+            mark_step(state, "semanticValidated", "completed", digest=manifest["digest"], resumedFromPublished=True)
+            write_onboarding_state(normalized(state["dataRoot"]), state)
+        validated = resumed_phase(profile, "semanticValidated", digest=manifest["digest"])
+        save_composite_result(evidence_dir, "08-semantic-validate-dry.json", validated, files)
+    else:
+        validate_dry = semantic_validate_command(argparse.Namespace(
+            install_root=args.install_root,
+            data_root=args.data_root,
+            profile=profile,
+            apply=False,
+            include_stack_trace=False,
+        ))
+        save_composite_result(evidence_dir, "08-semantic-validate-dry.json", validate_dry, files)
+        if not args.approve_validate:
+            return {
+                "success": True,
+                "schemaVersion": "foggy-deepseek-semantic-run/v1",
+                "profile": profile,
+                "phaseStatus": "awaiting-validate-approval",
+                "evidenceDir": str(evidence_dir),
+                "evidenceFiles": files,
+                "next": "rerun with --approve-validate after the validation catalog mutation is approved",
+                "productionReady": False,
+            }
+        validated = semantic_validate_command(argparse.Namespace(
+            install_root=args.install_root,
+            data_root=args.data_root,
+            profile=profile,
+            apply=True,
+            include_stack_trace=False,
+        ))
     save_composite_result(evidence_dir, "09-semantic-validate-apply.json", validated, files)
-    publish_dry = semantic_publish_command(argparse.Namespace(
-        install_root=args.install_root,
-        data_root=args.data_root,
-        profile=profile,
-        apply=False,
-        replace_bundle=False,
-        watch=False,
-        prune=False,
-    ))
-    save_composite_result(evidence_dir, "10-semantic-publish-dry.json", publish_dry, files)
-    if not args.approve_publish:
+    state = read_onboarding_state(normalized(state["dataRoot"]), profile)
+    if published_digest_matches(state, manifest["digest"]):
+        published = resumed_phase(
+            profile,
+            "semanticPublished",
+            digest=manifest["digest"],
+            bundleName=state["semantic"]["bundleName"],
+        )
+        save_composite_result(evidence_dir, "10-semantic-publish-dry.json", published, files)
+    else:
+        publish_dry = semantic_publish_command(argparse.Namespace(
+            install_root=args.install_root,
+            data_root=args.data_root,
+            profile=profile,
+            apply=False,
+            replace_bundle=False,
+            watch=False,
+            prune=False,
+        ))
+        save_composite_result(evidence_dir, "10-semantic-publish-dry.json", publish_dry, files)
+        if not args.approve_publish:
+            return {
+                "success": True,
+                "schemaVersion": "foggy-deepseek-semantic-run/v1",
+                "profile": profile,
+                "phaseStatus": "awaiting-publish-approval",
+                "evidenceDir": str(evidence_dir),
+                "evidenceFiles": files,
+                "next": "rerun with --approve-validate --approve-publish after publication is approved",
+                "productionReady": False,
+            }
+        published = semantic_publish_command(argparse.Namespace(
+            install_root=args.install_root,
+            data_root=args.data_root,
+            profile=profile,
+            apply=True,
+            replace_bundle=False,
+            watch=False,
+            prune=False,
+        ))
+    save_composite_result(evidence_dir, "11-semantic-publish-apply.json", published, files)
+    state = read_onboarding_state(normalized(state["dataRoot"]), profile)
+    verified_step = state.get("steps", {}).get("semanticVerified", {})
+    payload_digest = sha256(payload_path)
+    if (
+        verified_step.get("status") == "completed"
+        and verified_step.get("queryModel") == declared_query_model
+        and verified_step.get("queryPayloadDigest") == payload_digest
+    ):
+        resumed = resumed_phase(
+            profile,
+            "semanticVerified",
+            queryModel=declared_query_model,
+            queryValidated=True,
+            queryExecuted=True,
+            rowCount=verified_step.get("rowCount"),
+            queryPayloadDigest=payload_digest,
+        )
+        save_composite_result(evidence_dir, "12-query-validate.json", resumed, files)
+        save_composite_result(evidence_dir, "13-query-execute.json", resumed, files)
+        status = onboarding_status_command(argparse.Namespace(
+            install_root=args.install_root, data_root=args.data_root, profile=profile,
+        ))
+        save_composite_result(evidence_dir, "14-status.json", status, files)
         return {
             "success": True,
             "schemaVersion": "foggy-deepseek-semantic-run/v1",
             "profile": profile,
-            "phaseStatus": "awaiting-publish-approval",
+            "phaseStatus": "completed",
+            "resumed": True,
+            "queryModel": declared_query_model,
+            "queryValidated": True,
+            "queryExecuted": True,
+            "rowCount": verified_step.get("rowCount"),
             "evidenceDir": str(evidence_dir),
             "evidenceFiles": files,
-            "next": "rerun with --approve-validate --approve-publish after publication is approved",
             "productionReady": False,
         }
-
-    published = semantic_publish_command(argparse.Namespace(
-        install_root=args.install_root,
-        data_root=args.data_root,
-        profile=profile,
-        apply=True,
-        replace_bundle=False,
-        watch=False,
-        prune=False,
-    ))
-    save_composite_result(evidence_dir, "11-semantic-publish-apply.json", published, files)
     query_validated = semantic_verify_command(argparse.Namespace(
         install_root=args.install_root,
         data_root=args.data_root,
         profile=profile,
-        query_model=args.query_model,
+        query_model=declared_query_model,
         query_payload=args.query_payload,
         execute=False,
     ))
@@ -2101,7 +2328,7 @@ def semantic_run_command(args: argparse.Namespace) -> dict:
         install_root=args.install_root,
         data_root=args.data_root,
         profile=profile,
-        query_model=args.query_model,
+        query_model=declared_query_model,
         query_payload=args.query_payload,
         execute=True,
     ))
@@ -2280,13 +2507,13 @@ def build_parser() -> argparse.ArgumentParser:
     status = sub.add_parser("onboard-status")
     status.add_argument("--install-root")
     status.add_argument("--data-root")
-    status.add_argument("--profile", default="default")
+    status.add_argument("--profile")
     status.set_defaults(handler=onboarding_status_command)
 
     resume = sub.add_parser("onboard-resume")
     resume.add_argument("--install-root")
     resume.add_argument("--data-root")
-    resume.add_argument("--profile", default="default")
+    resume.add_argument("--profile")
     resume.set_defaults(handler=onboarding_resume_command)
 
     datasource_run = sub.add_parser("onboard-datasource-run")
@@ -2322,7 +2549,7 @@ def build_parser() -> argparse.ArgumentParser:
     datasource_configure = sub.add_parser("datasource-configure")
     datasource_configure.add_argument("--install-root")
     datasource_configure.add_argument("--data-root")
-    datasource_configure.add_argument("--profile", default="default")
+    datasource_configure.add_argument("--profile")
     datasource_configure.add_argument("--apply", action="store_true")
     datasource_configure.add_argument("--replace", action="store_true")
     datasource_configure.set_defaults(handler=datasource_configure_command)
@@ -2330,14 +2557,14 @@ def build_parser() -> argparse.ArgumentParser:
     datasource_verify = sub.add_parser("datasource-verify")
     datasource_verify.add_argument("--install-root")
     datasource_verify.add_argument("--data-root")
-    datasource_verify.add_argument("--profile", default="default")
+    datasource_verify.add_argument("--profile")
     datasource_verify.add_argument("--bind", action="store_true")
     datasource_verify.set_defaults(handler=datasource_verify_command)
 
     schema_discover = sub.add_parser("schema-discover")
     schema_discover.add_argument("--install-root")
     schema_discover.add_argument("--data-root")
-    schema_discover.add_argument("--profile", default="default")
+    schema_discover.add_argument("--profile")
     schema_discover.add_argument("--schema", action="append")
     schema_discover.add_argument("--pattern")
     schema_discover.add_argument("--table", action="append")
@@ -2350,14 +2577,14 @@ def build_parser() -> argparse.ArgumentParser:
     semantic_draft = sub.add_parser("semantic-draft")
     semantic_draft.add_argument("--install-root")
     semantic_draft.add_argument("--data-root")
-    semantic_draft.add_argument("--profile", default="default")
+    semantic_draft.add_argument("--profile")
     semantic_draft.add_argument("--semantic-plan", required=True)
     semantic_draft.set_defaults(handler=semantic_draft_command)
 
     semantic_validate = sub.add_parser("semantic-validate")
     semantic_validate.add_argument("--install-root")
     semantic_validate.add_argument("--data-root")
-    semantic_validate.add_argument("--profile", default="default")
+    semantic_validate.add_argument("--profile")
     semantic_validate.add_argument("--apply", action="store_true")
     semantic_validate.add_argument("--include-stack-trace", action="store_true")
     semantic_validate.set_defaults(handler=semantic_validate_command)
@@ -2365,7 +2592,7 @@ def build_parser() -> argparse.ArgumentParser:
     semantic_publish = sub.add_parser("semantic-publish")
     semantic_publish.add_argument("--install-root")
     semantic_publish.add_argument("--data-root")
-    semantic_publish.add_argument("--profile", default="default")
+    semantic_publish.add_argument("--profile")
     semantic_publish.add_argument("--apply", action="store_true")
     semantic_publish.add_argument("--replace-bundle", action="store_true")
     semantic_publish.add_argument("--watch", action="store_true")
@@ -2375,7 +2602,7 @@ def build_parser() -> argparse.ArgumentParser:
     semantic_verify = sub.add_parser("semantic-verify")
     semantic_verify.add_argument("--install-root")
     semantic_verify.add_argument("--data-root")
-    semantic_verify.add_argument("--profile", default="default")
+    semantic_verify.add_argument("--profile")
     semantic_verify.add_argument("--query-model")
     semantic_verify.add_argument("--query-payload", required=True)
     semantic_verify.add_argument("--execute", action="store_true")