oh-my-llmwikimode 1.4.0 → 1.6.0

package/docs/design/EOS_CHAT_HOME_IA.md

@@ -10,6 +10,16 @@
 
 The user starts with Chat-first capture: saying what they want so Eos captures that intent as a local review-required artifact, then makes it visible in `Side Review`. Chat does not execute shell commands, providers, agents, wiki promotion, git actions, or background work by itself.
 
+EOS Workspace uses the **Local AI Operating Workbench** shell:
+
+- left app rail for Home, Chat, Side Review, and future evidence/status surfaces.
+- top workspace tabs for keeping multiple work surfaces open while the user compares context.
+- main work area for the active capture, review, or evidence surface.
+- right inspector for artifact metadata, source paths, evidence, and prepared decision details.
+- bottom status strip for Local Only, Review Required, Not Applied, daemon/token state, and harness readiness.
+
+The shell is web-service first. It is not a VS Code extension app, and it does not require a VSIX runtime.
+
 ## 2. Primary promise
 
 Use this product promise when shaping UI copy:
@@ -20,12 +30,16 @@ Tell Eos what you want to prepare. Eos captures it for local review before anyth
 
 ## 3. Required regions
 
-1. **Header rail** - `EOS Workspace`, short local workspace status, and links to `Eos Chat` and `Side Review`.
-2. **Safety strip** - always-visible copy: `Local review workspace. Nothing is applied automatically.`
-3. **Welcome state** - explains chat-first workflow without starter chips.
-4. **Status cards** - wiki status, review queue count, and harness readiness in compact cards.
-5. **Message list** - local acknowledgements only; no execution transcript unless a future approved execution flow exists.
-6. **Composer** - bottom input with a short placeholder and explicit send button.
+1. **Left app rail** - persistent navigation for `EOS Workspace`, `Eos Chat`, and `Side Review`.
+2. **Top workspace tabs** - browser-like open surfaces for Home, Chat, Side Review, and future evidence panels.
+3. **Header rail** - `EOS Workspace`, short local workspace status, and links to `Eos Chat` and `Side Review`.
+4. **Safety strip** - always-visible copy: `Local review workspace. Nothing is applied automatically.`
+5. **Welcome state** - explains chat-first workflow without starter chips.
+6. **Status cards** - wiki status, review queue count, and harness readiness in compact cards.
+7. **Main work area** - local acknowledgements and the active task surface only; no execution transcript unless a future approved execution flow exists.
+8. **Right inspector** - optional artifact, evidence, and prepared decision detail surface.
+9. **Composer** - bottom input with a short placeholder and explicit send button.
+10. **Bottom status strip** - local-only, review-required, Not Applied, and route/auth status.
 
 ## 4. Empty state copy
 
@@ -83,9 +97,13 @@ Do not use these labels in the Eos Chat MVP:
 
 - `GET /chat/` serves the Eos Chat local UI.
 - `GET /chat` redirects to `/chat/`.
-- `GET /workspace/` serves the canonical EOS Workspace Home.
+- `GET /workspace/` serves the canonical operating workbench and EOS Workspace Home.
 - `GET /workspace` redirects to `/workspace/`.
+- `GET /side-review/` serves the review desk for local artifacts, evidence, and prepare-only decision notes.
 - `GET /api/home` remains a read-only home data snapshot.
+- `POST /api/agent/side-review/approval-requests` prepares a review-required approval request from an existing `prepare_approval` Side Review decision artifact only.
+- `GET /api/workspace/artifacts/inspect` returns whitelisted read-only artifact inspector data by `{type,id}` only.
+- `GET /api/workspace/timeline-status` returns a local lifecycle timeline/status panel derived from EOS local artifacts only.
 - `POST /api/chat/requests` creates a review-required local artifact only.
 
 ## 12. Browser-first Workspace Slice
@@ -98,7 +116,9 @@ Do not use these labels in the Eos Chat MVP:
 - Review-required.
 - No hidden execution.
 - No source wiki mutation.
-- No hosted sync.
+- Hosted sync is deferred.
+- Production Discord control is deferred.
+- Marketplace, account, payment, publish, push, and package split work are deferred.
 - No auto-promotion, auto-merge, auto-delete, or auto-push.
 - Browser UI uses self-only CSP, local assets, and text-node rendering.
 
@@ -134,3 +154,37 @@ Required dashboard groups:
 - `System Health` - explains local load errors or confirms local review data is readable.
 
 The Chat home panel may show compact `Next Safe Actions` and `Recent Requests`, but these are navigation/review aids only. They must not become starter chips, execution shortcuts, provider dispatch, or hidden agent controls.
+
+## 13. Workspace completion snapshot - 2026-06-01
+
+`GET /api/home` now includes an `operating_snapshot` read model for the browser workbench.
+
+Stable fields:
+
+- `operating_snapshot.version: 2`
+- `operating_snapshot.shell.motif: Local AI Operating Workbench`
+- `operating_snapshot.shell.regions`: `left_app_rail`, `top_workspace_tabs`, `main_work_area`, `right_inspector`, `bottom_status_strip`
+- `operating_snapshot.route_roles`: `/workspace/` as canonical operating workbench, `/chat/` as compatibility inbox, `/side-review/` as review desk
+- `operating_snapshot.artifact_lifecycle`: capture request -> local artifact -> Side Review card -> prepare-only decision artifact -> future explicit approval flow
+- `review_queue.side_review_decision_recent`: latest prepared decision artifacts for the right inspector/Home summary
+
+The snapshot is a read model only. It must not become an execution queue, approval queue, hosted sync contract, or source wiki mutation path.
+
+## 14. Approval Inspector workspace slice - 2026-06-01
+
+`EOS Workspace` now includes an Approval Queue and Artifact Inspector for review-required approval request artifacts.
+
+Stable surfaces:
+
+- `review_queue.approval_request_recent`: latest local approval request artifacts visible in Home/Workspace.
+- `approval_surface`: local approval queue metadata and route hints for the browser workbench.
+- `/api/agent/side-review/approval-requests`: prepare-only route from `prepare_approval` Side Review decisions to approval request artifacts.
+- `/api/workspace/artifacts/inspect`: safe inspector route for whitelisted artifact types and ids.
+- `/api/workspace/timeline-status`: local lifecycle timeline and Timeline Gate status.
+- Workspace regions: `Approval Queue`, `Artifact Inspector`, `Lifecycle Timeline`, and `Timeline Gate`.
+
+Safety contract:
+
+- Approval Queue is a review queue, not an execution queue.
+- Artifact Inspector must reject raw local paths, traversal, unsupported types, symlinks, oversized artifacts, and malformed JSON without leaking secrets or user-home paths.
+- Timeline Gate may show `approved_not_executed`, but this is a review state only. It must not imply shell, git, provider, Discord, sync, publish, merge, push, or source wiki mutation work has happened.

package/docs/design/EOS_CHAT_OPERATING_LOOP.md

@@ -10,6 +10,12 @@ EOS Workspace is the browser-first Home. Chat is the inbox. Side Review is the r
 
 The user writes a request through Chat-first capture on `/workspace/` or the compatibility `/chat/` surface. Eos files it as a local review item, adds a deterministic intent hint, and places it on the `Side Review` desk. Nothing is executed or applied just because the request was captured.
 
+The UI motif is a Local AI Operating Workbench:
+
+- `/workspace/` is the canonical operating workbench with the left app rail, top workspace tabs, main work area, right inspector, and bottom status strip.
+- `/chat/` is the compatibility inbox for focused capture.
+- `/side-review/` is the review desk for review-required artifacts, evidence, prepared decisions, and completion reports.
+
 ## 2. Operating loop
 
 ```text
@@ -106,3 +112,17 @@ This slice must not add:
 ## 9. Workspace Home coordination
 
 `/workspace/` is the canonical browser Home for this slice. It exposes `EOS Workspace`, `Chat-first capture`, `Capture for Review`, `Open Chat`, and `Open Side Review` while keeping every output local-only, review-required, and Not Applied.
+
+The review-required artifact lifecycle remains capture request -> local artifact -> Side Review card -> prepare-only decision artifact -> future explicit approval flow. Hosted sync and production Discord control are deferred; marketplace, package split, publish, push, hidden execution, and source wiki mutation stay out of scope.
+
+## 10. Completion proof - 2026-06-01
+
+The operating loop is now verified as a browser-first product slice:
+
+- A request can be captured through the local HTTP/browser flow and surfaced as Home queue pressure.
+- The captured request appears in Side Review with evidence and safe prepare-only actions.
+- Preparing a decision writes `.system/eos/side-review/decisions/{id}.json` and Home shows it as a recent prepared decision.
+- Source markdown checksums remain unchanged; only `.system/eos` review artifacts are written.
+- Chrome desktop/mobile evidence confirms the workspace shell and route-specific surfaces render as nonblank local pages.
+
+Completion evidence lives under `.omo/ulw-loop/evidence/eos-workspace-completion-20260601/`.

package/docs/design/EOS_DESIGN.md

@@ -22,6 +22,22 @@ Eos is **not** a cloud assistant surface, marketing landing page, autonomous exe
 
 The interface should feel like a trustworthy local cockpit where conversation opens separate work panels, not a generic chatbot SaaS clone or button-heavy dashboard.
 
+**Local AI Operating Workbench** is the browser-service shell motif for EOS Workspace. It borrows the familiar shape of operating tools without turning EOS into a VS Code extension:
+
+- left app rail: persistent navigation for Workspace Home, Chat, Side Review, future evidence views, and status surfaces.
+- top workspace tabs: multiple open work surfaces can be kept visible like browser or IDE tabs.
+- main work area: the active surface owns the center of the screen and carries the primary task.
+- right inspector: optional evidence, artifact metadata, source path, decision detail, and review context.
+- bottom status strip: local-only state, review-required mode, Not Applied state, harness readiness, and route/auth status.
+
+Route roles stay explicit:
+
+- `/workspace/` is the canonical operating workbench and default browser Home.
+- `/chat/` is the compatibility inbox and focused capture surface.
+- `/side-review/` is the review desk for artifacts, evidence, prepared decisions, and completion reports.
+
+The review-required artifact lifecycle is: capture request -> local artifact -> Side Review card -> prepare-only decision artifact -> future explicit approval flow. Hosted sync, production Discord control, marketplace work, package split, publish, push, real execution, and automatic mutation are deferred until separate specs authorize them.
+
 Compatibility note: the VS Code extension design gate still tracks the earlier `Dawn Control Room` metaphor and the Korean chat prompt `무엇을 맡길까요?`. Treat both as compatible markers for the same calm, chat-first local command center direction, not as permission to add a dashboard-first or execution-first surface.
 
 ## Primary Surfaces for This Slice
@@ -298,3 +314,61 @@ Verification anchors:
 - `test/eos/home-data.test.js`
 - `test/eos/side-review-routes.test.js`
 - `test/eos/workspace-boundary-side-review-view-model.test.js`
+
+## Implemented EOS Workspace Completion Slice - 2026-06-01
+
+The EOS Workspace completion slice turns `/workspace/` into the canonical browser-first operating workbench.
+
+What changed:
+
+- `GET /api/home` now exposes operating snapshot v2 with the `Local AI Operating Workbench` motif, route roles, artifact lifecycle, recent chat requests, and recent prepared Side Review decisions.
+- `/workspace/` now renders the shell regions directly: left app rail, top workspace tabs, main work area, right inspector, and bottom status strip.
+- Chat capture remains available from `/workspace/` and `/chat/`; both routes create review-required local artifacts only.
+- Prepared Side Review decisions are visible from Home/Workspace as local review-required artifacts.
+- Desktop and mobile Chrome evidence is captured under `.omo/ulw-loop/evidence/eos-workspace-completion-20260601/`.
+
+Boundary:
+
+- The slice remains web-service first, not a VS Code extension.
+- It does not add hosted sync, production Discord control, marketplace/account/payment features, package splitting, npm publish, auto-apply, auto-promotion, auto-merge/delete, auto-push, hidden execution, or source wiki mutation.
+
+Verification anchors:
+
+- `test/eos/home-data.test.js`
+- `test/eos/workspace-home-routes.test.js`
+- `test/eos/uiux-product-shape.test.js`
+- `npm run test:eos`
+- `npm run verify:eos-workspace-completion`
+
+## Implemented EOS Workspace Approval Inspector Slice - 2026-06-01
+
+The EOS Workspace Approval Inspector slice makes approval requests first-class local review artifacts inside the browser-first workbench.
+
+What changed:
+
+- Approval request artifacts now live under `.system/eos/approval/requests/` with review-required lifecycle statuses, deterministic duplicate handling, and append-only audit metadata.
+- `GET /api/home` includes a local approval queue summary with recent approval request artifacts.
+- `POST /api/agent/side-review/approval-requests` prepares an approval request only from an existing `prepare_approval` Side Review decision artifact.
+- `GET /api/workspace/artifacts/inspect` exposes a whitelisted, read-only artifact inspector for approval requests and adjacent EOS artifacts.
+- `GET /api/workspace/timeline-status` exposes a local-only lifecycle timeline/status panel derived from chat, Side Review, approval, visual QA, and local evidence artifacts.
+- `/workspace/` renders Approval Queue, Artifact Inspector, Lifecycle Timeline, and Timeline Gate surfaces with Local Only, Review Required, and Not Applied safety labels.
+- Browser product evidence is captured under `.omo/ulw-loop/evidence/eos-approval-inspector-20260601/`.
+
+Boundary:
+
+- The slice remains web-service first, not a VS Code extension or VSIX.
+- Approval statuses such as `approved_not_executed` mean explicit review state only; they do not execute shell, git, provider, Discord, or wiki mutation actions.
+- Side Review approval request creation is prepare-only; it creates a local review artifact and never applies the underlying decision.
+- The inspector reads only whitelisted local artifacts by type/id, rejects raw paths and traversal, redacts secrets and user-home paths, and degrades safely on malformed artifacts.
+- This slice does not add hosted sync, production Discord control, marketplace/account/payment features, package splitting, npm publish, auto-apply, auto-promotion, auto-merge/delete, auto-push, hidden execution, or source wiki mutation.
+
+Verification anchors:
+
+- `test/eos/approval-request-artifacts.test.js`
+- `test/eos/approval-queue-read-model.test.js`
+- `test/eos/side-review-approval-requests.test.js`
+- `test/eos/artifact-inspector-view-model.test.js`
+- `test/eos/workspace-approval-inspector-routes.test.js`
+- `test/eos/timeline-status-panel.test.js`
+- `test/eos/approval-inspector-gate.test.js`
+- `npm run verify:eos-approval-inspector`

package/docs/design/EOS_SIDE_REVIEW_IA.md

@@ -8,6 +8,8 @@
 
 `Side Review` is the companion window for looking at structured material while `EOS Workspace` at `/workspace/` remains the browser-first Home and `Eos Chat` remains the compatibility capture surface.
 
+In the Local AI Operating Workbench shell, `/side-review/` is the review desk. It can be opened from the left app rail or held as a top workspace tab while the main work area stays on Chat or Home. Its cards may feed the right inspector with artifact paths, evidence, and prepared decision detail, while the bottom status strip continues to show Local Only, Review Required, and Not Applied state.
+
 It answers five questions:
 
 1. What is waiting?
@@ -356,3 +358,21 @@ The UI and API may summarize these proof fields, but must not convert them into
 ### Future boundary
 
 Real approval execution, source wiki mutation, promotion, merge, delete, push, release, npm publish, hosted sync, and Discord runtime control require a separate explicit product spec and are not part of this MVP.
+
+## 13. Workspace completion integration - 2026-06-01
+
+`Side Review` is now part of the EOS operating workbench loop rather than a standalone browser surface.
+
+Integration contract:
+
+- `/workspace/` links to Side Review as the review desk in the left app rail and top workspace tabs.
+- Prepared decision artifacts remain in `.system/eos/side-review/decisions/` and are summarized by Home through `review_queue.side_review_decision_recent`.
+- The Workspace right inspector may summarize recent prepared decisions, but it must not expose execution, approval, promotion, merge, delete, push, or source mutation controls.
+- The decision artifact lifecycle remains prepare-only until a future explicit approval flow is specified and separately verified.
+
+Verification anchors:
+
+- `test/eos/home-data.test.js`
+- `test/eos/side-review-routes.test.js`
+- `test/eos/workspace-home-routes.test.js`
+- `test/eos/uiux-product-shape.test.js`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-llmwikimode",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "LLM Wiki plugin for OpenCode ??auto-memory, retrieval, and knowledge promotion",
   "type": "module",
   "main": "./src/server.js",
@@ -29,6 +29,8 @@
     "test:security": "node --test test/security.test.js",
     "test:eos": "node --test test/eos/**/*.test.js",
     "verify:eos-workspace-product": "npm run test:eos && npm run verify:eos-boundary-policy && npm run verify:eos-boundary && npm run eos:a11y-snapshot -- --json",
+    "verify:eos-workspace-completion": "node scripts/verify-eos-workspace-completion.js",
+    "verify:eos-approval-inspector": "node scripts/verify-eos-approval-inspector.js",
     "verify:package": "node test/verify-package.test.js",
     "verify:docs": "node test/verify-docs.test.js",
     "verify:side-effects": "node scripts/side-effect-audit.js",

package/src/eos/approval/artifacts.js

@@ -0,0 +1,164 @@
+import { appendFile, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  APPROVAL_REQUEST_STATUSES,
+  createApprovalAuditEntry,
+  createApprovalRequestArtifact,
+  validateApprovalRequest,
+} from "./contract.js";
+
+export { APPROVAL_REQUEST_STATUSES } from "./contract.js";
+
+const AUDIT_ACTIONS = Object.freeze([
+  "approval_requested",
+  "reject_approval_request",
+]);
+
+function resolveUnderWikiRoot(wikiRoot, relativePath) {
+  const root = path.resolve(wikiRoot);
+  const target = path.resolve(root, ...relativePath.split("/"));
+  const relative = path.relative(root, target);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error("Eos approval artifact path escapes wiki root");
+  }
+  return target;
+}
+
+function resolveRequestArtifactPath(wikiRoot, relativePath) {
+  const target = resolveUnderWikiRoot(wikiRoot, relativePath);
+  const requestsRoot = path.resolve(getApprovalArtifactPaths(wikiRoot).requests);
+  const relative = path.relative(requestsRoot, target);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error("Eos approval artifact path escapes requests directory");
+  }
+  return target;
+}
+
+export function getApprovalArtifactPaths(wikiRoot) {
+  const root = path.join(wikiRoot, ".system", "eos", "approval");
+  return Object.freeze({
+    root,
+    requests: path.join(root, "requests"),
+    auditFile: path.join(root, "audit.jsonl"),
+  });
+}
+
+export async function ensureApprovalArtifactStructure(wikiRoot) {
+  const paths = getApprovalArtifactPaths(wikiRoot);
+  await mkdir(paths.requests, { recursive: true });
+  return paths;
+}
+
+export async function prepareApprovalRequestArtifact(wikiRoot, input = {}, options = {}) {
+  if (!wikiRoot || typeof wikiRoot !== "string") {
+    throw new Error("wikiRoot is required for Eos approval artifacts");
+  }
+
+  const now = options.now instanceof Date ? options.now : new Date(options.now || Date.now());
+  const validation = validateApprovalRequest(input);
+  if (!validation.valid) {
+    await appendApprovalAudit(wikiRoot, "reject_approval_request", {
+      source_decision_id: input.source_decision_id || "",
+      requested_action: input.requested_action || "",
+      reason: validation.errors.join("; "),
+    }, { ...options, now });
+    return rejected(validation.errors.join("; "));
+  }
+
+  const prepared = createApprovalRequestArtifact(validation.value, { ...options, now });
+  const resolvedArtifactPath = resolveRequestArtifactPath(wikiRoot, prepared.artifactPath);
+  const existing = await readExistingJson(resolvedArtifactPath);
+  if (existing.exists) {
+    return Object.freeze({
+      success: true,
+      duplicate: true,
+      request: existing.value,
+      artifactPath: prepared.artifactPath,
+      executed: false,
+      sourceEntryMutated: false,
+    });
+  }
+
+  await ensureApprovalArtifactStructure(wikiRoot);
+  await writeFile(resolvedArtifactPath, `${JSON.stringify(prepared.artifact, null, 2)}\n`, {
+    encoding: "utf-8",
+    flag: "wx",
+  });
+  await appendApprovalAuditEntry(wikiRoot, prepared.auditEntry);
+
+  return Object.freeze({
+    success: true,
+    duplicate: false,
+    request: prepared.artifact,
+    artifactPath: prepared.artifactPath,
+    audit: prepared.auditEntry,
+    auditPath: ".system/eos/approval/audit.jsonl",
+    executed: false,
+    sourceEntryMutated: false,
+  });
+}
+
+export async function readApprovalRequestArtifacts(wikiRoot) {
+  const paths = getApprovalArtifactPaths(wikiRoot);
+  const requests = [];
+  const load_errors = [];
+  try {
+    const entries = await readdir(paths.requests, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+      const filePath = path.join(paths.requests, entry.name);
+      try {
+        const artifact = JSON.parse(await readFile(filePath, "utf-8"));
+        if (artifact?.type === "eos_approval_request" && APPROVAL_REQUEST_STATUSES.includes(artifact.status)) {
+          requests.push(artifact);
+        }
+      } catch (error) {
+        load_errors.push({ path: filePath, error: error instanceof Error ? error.message : String(error) });
+      }
+    }
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  return Object.freeze({
+    paths,
+    requests: Object.freeze(requests.sort((left, right) => String(left.id).localeCompare(String(right.id)))),
+    load_errors: Object.freeze(load_errors),
+    summary: Object.freeze({ requests: requests.length, load_errors: load_errors.length }),
+  });
+}
+
+async function readExistingJson(filePath) {
+  try {
+    return Object.freeze({ exists: true, value: JSON.parse(await readFile(filePath, "utf-8")) });
+  } catch (error) {
+    if (error?.code === "ENOENT") return Object.freeze({ exists: false, value: null });
+    throw error;
+  }
+}
+
+async function appendApprovalAudit(wikiRoot, action, entry = {}, options = {}) {
+  const payload = {
+    ...createApprovalAuditEntry(action, entry, options),
+    reason: entry.reason || "",
+  };
+  await appendApprovalAuditEntry(wikiRoot, payload);
+  return payload;
+}
+
+async function appendApprovalAuditEntry(wikiRoot, entry) {
+  if (!AUDIT_ACTIONS.includes(entry.action)) {
+    throw new Error(`Unsupported Eos approval audit action: ${entry.action}`);
+  }
+  const paths = await ensureApprovalArtifactStructure(wikiRoot);
+  await appendFile(paths.auditFile, `${JSON.stringify(entry)}\n`, "utf-8");
+}
+
+function rejected(error) {
+  return Object.freeze({
+    success: false,
+    error,
+    executed: false,
+    sourceEntryMutated: false,
+  });
+}

package/src/eos/approval/contract.js

@@ -0,0 +1,165 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+export const APPROVAL_REQUEST_STATUSES = Object.freeze([
+  "review_required",
+  "blocked",
+  "approved_not_executed",
+  "handoff_prepared",
+  "rejected",
+]);
+
+export const APPROVAL_ACTION = "prepare_handoff";
+
+const SUPPORTED_SOURCE_ROOTS = Object.freeze([
+  ".system/eos/chat/requests/",
+  ".system/eos/side-review/decisions/",
+  ".system/eos/approval/requests/",
+  ".system/eos/visual-qa/",
+  ".omo/ulw-loop/evidence/",
+]);
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function iso(value) {
+  return (value instanceof Date ? value : new Date(value || Date.now())).toISOString();
+}
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (isRecord(value)) {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function shortHash(value) {
+  return createHash("sha256").update(stableJson(value)).digest("hex").slice(0, 12);
+}
+
+function safeId(value, fallback = "approval") {
+  return String(value || fallback)
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80) || fallback;
+}
+
+export function relativeRequestPath(id) {
+  return path.posix.join(".system", "eos", "approval", "requests", `${id}.json`);
+}
+
+function normalizeRelativePath(value, field, options = {}) {
+  if (typeof value !== "string" || !value.trim()) return { error: `${field} is required` };
+  const normalized = value.trim().replaceAll("\\", "/");
+  if (path.isAbsolute(normalized) || normalized.includes("://")) return { error: `${field} must be a safe relative path` };
+  const collapsed = path.posix.normalize(normalized);
+  if (collapsed.startsWith("../") || collapsed === ".." || collapsed.startsWith("/")) {
+    return { error: `${field} must stay inside the wiki root` };
+  }
+  if (options.supportedRoot && !SUPPORTED_SOURCE_ROOTS.some((root) => collapsed.startsWith(root))) {
+    return { error: `${field} must use a supported approval source root` };
+  }
+  return { value: collapsed };
+}
+
+export function validateApprovalRequest(input = {}) {
+  const errors = [];
+  const sourceDecisionId = typeof input.source_decision_id === "string" ? input.source_decision_id.trim() : "";
+  const requestedAction = typeof input.requested_action === "string" ? input.requested_action.trim() : "";
+  const sourceArtifactPath = normalizeRelativePath(input.source_artifact_path, "source_artifact_path", { supportedRoot: true });
+  const sourcePath = input.source_path ? normalizeRelativePath(input.source_path, "source_path") : { value: null };
+  const evidence = Array.isArray(input.evidence) ? input.evidence : [];
+
+  if (!sourceDecisionId) errors.push("source_decision_id is required");
+  if (requestedAction !== APPROVAL_ACTION) errors.push(`requested_action must be ${APPROVAL_ACTION}`);
+  if (input.status && !APPROVAL_REQUEST_STATUSES.includes(input.status)) errors.push("status is not supported");
+  if (sourceArtifactPath.error) errors.push(sourceArtifactPath.error);
+  if (sourcePath.error) errors.push(sourcePath.error);
+  if (evidence.length === 0) errors.push("evidence is required");
+
+  if (errors.length > 0) return Object.freeze({ valid: false, errors: Object.freeze(errors) });
+
+  return Object.freeze({
+    valid: true,
+    value: Object.freeze({
+      source_decision_id: sourceDecisionId,
+      source_artifact_path: sourceArtifactPath.value,
+      requested_action: requestedAction,
+      reason: typeof input.reason === "string" ? input.reason.trim() : "",
+      source_path: sourcePath.value,
+      evidence: Object.freeze(evidence.map((item) => String(item).trim()).filter(Boolean)),
+      requested_by: typeof input.requested_by === "string" && input.requested_by.trim()
+        ? input.requested_by.trim()
+        : "eos-approval",
+    }),
+  });
+}
+
+export function createApprovalRequestArtifact(request, options = {}) {
+  const seed = {
+    source_decision_id: request.source_decision_id,
+    source_artifact_path: request.source_artifact_path,
+    requested_action: request.requested_action,
+    evidence: request.evidence,
+  };
+  const id = `approval-${safeId(request.source_decision_id)}-${safeId(request.requested_action)}-${shortHash(seed)}`;
+  const artifactPath = relativeRequestPath(id);
+  const auditEntry = createApprovalAuditEntry("approval_requested", request, options, { requestId: id, artifactPath });
+  return Object.freeze({
+    artifactPath,
+    artifact: Object.freeze({
+      schema_version: 1,
+      type: "eos_approval_request",
+      id,
+      source_decision_id: request.source_decision_id,
+      source_artifact_path: request.source_artifact_path,
+      requested_action: request.requested_action,
+      reason: request.reason,
+      source_path: request.source_path,
+      evidence: request.evidence,
+      status: "review_required",
+      requested_by: request.requested_by,
+      safety_flags: Object.freeze({
+        review_required: true,
+        approved_not_executed: false,
+        executed: false,
+        source_entry_mutated: false,
+      }),
+      boundaries: Object.freeze({
+        no_hidden_execution: true,
+        no_source_mutation: true,
+        auto_apply: false,
+        auto_promote: false,
+        auto_merge: false,
+        auto_delete: false,
+        auto_push: false,
+        auto_publish: false,
+        hosted_sync: false,
+      }),
+      audit: Object.freeze([auditEntry]),
+      created_at: iso(options.now),
+      updated_at: iso(options.now),
+      artifact_path: artifactPath,
+    }),
+    auditEntry,
+  });
+}
+
+export function createApprovalAuditEntry(action, request, options = {}, refs = {}) {
+  return Object.freeze({
+    schema_version: 1,
+    action,
+    recorded_at: iso(options.now),
+    actor: options.actor || "eos-approval",
+    request_id: refs.requestId || null,
+    artifact_path: refs.artifactPath || null,
+    source_decision_id: request.source_decision_id || "",
+    requested_action: request.requested_action || "",
+    executed: false,
+    live_execution: false,
+    source_entry_mutated: false,
+  });
+}