slidemind 0.3.20 → 0.4.0

package/src/workspace/task-actions.mjs

@@ -0,0 +1,215 @@
+// What a task's answer DOES (tasks.md 4.4): the authoritative action behind
+// `respondTask`'s `invoke`, per task kind and per deck owner.
+//
+//   plan-edit      done             pack: validate (+ re-render) · core: respondPlan
+//   plan-approval  approve          pack: approve prepare → finalize · core: respondPlan
+//                  request-changes  the comment on the task; the record is untouched
+//   preview-review approve/comment  core: respondPreview
+//   sync-conflict  resolve          sync.resolveConflict (7.5)
+//
+// "Done planning" and "Approve" are two tasks: done only proves the plan is
+// structurally valid and refreshes the page; approve stamps the frozen approved
+// plan and context through the pack. The pack, not this module, owns approval
+// semantics — this module carries the subject hash in and the evidence out.
+//
+// Two answers need the network, and the network is never called under the deck
+// lock (contracts §5): a SHARED approval and a conflict resolution. Inside the
+// response transaction `invokeTaskAction` only prepares and answers
+// `approval_requires_sync` / `conflict_requires_resolve`; `respondTaskAction`
+// — the entry point routes call — then runs the coordinator (sync.mjs) with
+// its own operations and records the evidence in a second, plain transaction.
+
+import os from "node:os";
+import path from "node:path";
+
+import { loadPlanState, planSubjectHash, respondPlan } from "../builders/plan.mjs";
+import { loadReviewState, previewHash, respondPreview } from "../builders/review.mjs";
+import { resolveWorkspace } from "../lib/deck-paths.mjs";
+import { readRecordState } from "../lib/record-state.mjs";
+import { dispatchAdapter } from "./adapters.mjs";
+import { coded } from "./registry.mjs";
+import { approveShared, readSync, resolveConflict } from "./sync.mjs";
+import { KINDS, getTask, respondTask, supersedeTask } from "./tasks.mjs";
+
+export const CORE_ADAPTER = "core";
+
+/** The actions a task of `kind` offers (contracts §4). Adapters do not extend the set in v1. */
+export const taskActionsFor = (kind) => KINDS[kind] ?? null;
+
+const blocked = (code, message, details) => ({ blocked: { code, message, ...(details ? { details } : {}) } });
+const wsOf = (deckRoot) => resolveWorkspace(path.resolve(deckRoot));
+// An installed pack (`entry`), or — as in sync.mjs — an in-process stand-in exposing the same methods.
+const isPack = (adapter) => Boolean(adapter?.entry || typeof adapter?.read === "function");
+const packCall = (adapter, { method, deckRoot, payload = {}, operationId, ownerToken }) => {
+  if (adapter.entry) return dispatchAdapter(adapter.entry, { method, deckRoot, payload, operationId, ownerToken });
+  const fn = adapter[{ "import-workbook": "importWorkbook" }[method] ?? method];
+  if (typeof fn !== "function") return Promise.resolve({ status: "error", error: { code: "extension_incompatible", message: `no ${method}` } });
+  return Promise.resolve(fn.call(adapter, payload, ownerToken)).then(({ ok, code, message, ...data }) => (ok ? { status: "ok", data } : { status: "blocked", error: { code: code ?? "validation_failed", message: message ?? code }, data }));
+};
+
+/** Who answered: a self-declared name from the page, else the OS account — never invented. */
+export function taskActor(payload = {}, fallback = os.userInfo().username) {
+  const declared = typeof payload.approvedBy === "string" ? payload.approvedBy.trim() : "";
+  return declared ? { actor: declared, selfDeclared: true } : { actor: fallback, selfDeclared: false };
+}
+
+/**
+ * What a task is about, derived from the deck — never from the caller. A pack
+ * deck answers through its adapter's `read`; a core deck hashes plan.md, or the
+ * reviewed slides for preview-review (the same hash respondPreview checks).
+ */
+export async function deriveTaskSubject({ deckRoot, adapter, kind }) {
+  if (isPack(adapter) && kind !== "preview-review") {
+    const res = await packCall(adapter, { method: "read", deckRoot });
+    if (res.status !== "ok") {
+      throw Object.assign(new Error(res.error?.message ?? `adapter read ${res.status}`), { code: res.error?.code ?? "extension_incompatible" });
+    }
+    return { adapterId: adapter.id, subject: { hash: res.data.hash, remoteETag: res.data.remoteETag ?? null } };
+  }
+  const ws = wsOf(deckRoot);
+  try {
+    const hash = kind === "preview-review" ? previewHash(ws) : planSubjectHash(ws);
+    return { adapterId: CORE_ADAPTER, subject: { hash, remoteETag: null } };
+  } catch (err) {
+    if (err?.code !== "ENOENT") throw err;
+    throw Object.assign(new Error("nothing to ask about yet: the plan does not exist"), { code: "validation_failed" });
+  }
+}
+
+// The generic gates answer `{ status, body }`; a task wants evidence or a refusal.
+function fromGate(res, task, record) {
+  if (res.status === 200) return { evidence: { record, hash: res.body.hash } };
+  const e = res.body.error;
+  return blocked(e.code === "plan_missing" ? "stale_subject" : e.code, e.message, e.details);
+}
+
+async function packAction({ deckRoot, adapter, task, response, token, payload }) {
+  const call = (method, p) => packCall(adapter, { method, deckRoot, payload: p, operationId: response.operationId, ownerToken: token });
+  const current = await call("read", {});
+  if (current.status !== "ok") return blocked(current.error.code, current.error.message);
+  if (current.data.hash !== task.subject.hash) {
+    return blocked("stale_subject", "the plan changed since this task was requested", { current: current.data.hash, supersede: true });
+  }
+  switch (response.action) {
+    case "done": {
+      const v = await call("validate", {});
+      if (v.status !== "ok") return blocked(v.error.code, v.error.message, v.error.details);
+      if (!v.data.valid) return blocked("validation_failed", "the plan is not valid yet; fix the issues and mark it done again", { errors: v.data.errors });
+      const r = await call("render", { viewId: "plan" });
+      if (r.status !== "ok") return blocked(r.error.code, r.error.message);
+      return { evidence: { record: "plan", hash: task.subject.hash } };
+    }
+    case "request-changes":
+      return { evidence: { record: "task", hash: task.subject.hash } };
+    case "approve": {
+      const prep = await call("approve", { phase: "prepare", approvedBy: response.actor, expectedHash: task.subject.hash, approvedAt: response.at });
+      if (prep.status !== "ok") return blocked(prep.error.code, prep.error.message, { ...(prep.error.details ?? {}), supersede: prep.error.code === "stale_subject" });
+      if (prep.data.shared) {
+        // the network is not called under this lock: respondTaskAction runs approveShared with `prepared`, then records the evidence
+        return blocked("approval_requires_sync", "this plan is shared; the reviewed version is synchronized before it is approved", { prepared: prep.data.prepared });
+      }
+      const fin = await call("approve", { phase: "finalize", prepared: prep.data.prepared });
+      // finalize writes: a pack that refused wrote nothing, a pack that died may have — that outcome is unknown, so the intent stays for recovery
+      if (fin.status === "blocked") return blocked(fin.error.code, fin.error.message, fin.error.details);
+      if (fin.status !== "ok") throw Object.assign(new Error(`approval outcome unknown: ${fin.error.message}`), { code: "outcome_unknown", details: fin.error.details });
+      return { evidence: { record: `context.json#${fin.data.planHash}`, hash: task.subject.hash } };
+    }
+    default:
+      return blocked("not_implemented", `${response.action} has no workspace binding yet`);
+  }
+}
+
+/**
+ * `respondTask`'s invoke. `{ evidence }` when the action landed for exactly
+ * `task.subject.hash`; `{ blocked: { code, message, details } }` when nothing
+ * was written (stale subject, invalid plan, shared approval) — the task stays
+ * pending and its intent is cleared. `details.supersede` marks a subject that
+ * moved on, so the route voids the task.
+ */
+export async function invokeTaskAction({ deckRoot, adapter, task, response, token, payload = {} }) {
+  if (task.kind === "sync-conflict") {
+    // the resolution itself needs the latest remote: respondTaskAction runs sync.resolveConflict outside this lock
+    const c = readSync(wsOf(deckRoot)).conflict;
+    if (!c || c.expectedHash !== task.subject.hash) return blocked("stale_subject", "this conflict is no longer the current one", { supersede: true, conflictId: c?.conflictId ?? null });
+    if (!payload.value || typeof payload.value !== "object") return blocked("validation_failed", "a resolution carries the whole resolved plan as payload.value");
+    return blocked("conflict_requires_resolve", "the resolution is committed against the latest shared record", { conflictId: c.conflictId });
+  }
+  if (isPack(adapter) && task.kind !== "preview-review") return packAction({ deckRoot, adapter, task, response, token, payload });
+  const ws = wsOf(deckRoot);
+  const args = { action: response.action, expectedHash: task.subject.hash, payload: { ...payload, comments: payload.comments ?? (response.comment ? [response.comment] : undefined) }, actor: response.actor, operationId: response.operationId, at: response.at };
+  if (task.kind === "preview-review") return fromGate(respondPreview(ws, args), task, "state/review.json");
+  const res = fromGate(respondPlan(ws, args), task, "state/plan-review.json");
+  if (res.blocked?.code === "stale_subject") res.blocked.details = { ...(res.blocked.details ?? {}), supersede: true };
+  return res;
+}
+
+/** The signed-in account a SHARED approval is attributed to: the binding's backend session, or `client.identity` when injected. Null when nobody is signed in. */
+export function sharedIdentity(binding, { client = null, getSessionFor = null } = {}) {
+  if (typeof client?.identity === "string" && client.identity) return client.identity;
+  if (!binding?.backendURL || !getSessionFor) return null;
+  const name = getSessionFor(binding.backendURL)?.msGraphUsername;
+  return typeof name === "string" && name ? name : null;
+}
+
+/**
+ * The entry point for a task answer: `respondTask` with `invokeTaskAction`,
+ * plus the two answers whose action lives outside the response transaction.
+ *
+ *   approve on a shared plan   → attributed to the signed-in account (never a
+ *                                self-declared name; `login_required` without
+ *                                one), then sync.approveShared, then the
+ *                                evidence recorded
+ *   resolve on a conflict      → sync.resolveConflict, then the evidence recorded
+ *
+ * Throws what respondTask throws; a coordinator refusal is thrown with its code
+ * and `details.supersede` when the task was voided (the content moved on).
+ */
+export async function respondTaskAction(deckRoot, id, request, { adapter, client = null, owner, verify, getSessionFor = null } = {}) {
+  const ws = wsOf(deckRoot);
+  const task = getTask(deckRoot, id);
+  const binding = readRecordState(ws);
+  const shared = Boolean(binding?.url || (binding?.driveId && binding?.itemId));
+  let req = { ...request };
+  if (task?.kind === "plan-approval" && req.action === "approve" && shared && isPack(adapter)) {
+    const identity = sharedIdentity(binding, { client, getSessionFor: getSessionFor ?? (await import("../bridge/config.mjs")).getSessionFor });
+    if (!identity) throw coded("login_required", "a shared plan is approved as the signed-in Microsoft 365 account; run `slidemind login` first");
+    if (req.selfDeclared && req.actor !== identity) throw coded("validation_failed", `a shared approval is attributed to the signed-in account (${identity}), not to a typed name`);
+    req = { ...req, actor: identity, selfDeclared: false };
+  }
+  const payload = req.payload ?? {};
+  const invoke = (t, response, { token }) => invokeTaskAction({ deckRoot, adapter, task: t, response, token, payload });
+  try {
+    return await respondTask(deckRoot, id, req, { invoke, owner, verify });
+  } catch (err) {
+    if (err?.code !== "approval_requires_sync" && err?.code !== "conflict_requires_resolve") throw err;
+    const response = { operationId: req.operationId, action: req.action, at: new Date().toISOString(), actor: req.actor, comment: payload.comment ?? null, ...(req.selfDeclared ? { selfDeclared: true } : {}) };
+    const current = getTask(deckRoot, id);
+    const out =
+      err.code === "approval_requires_sync"
+        ? await approveShared(ws, { adapter, client, owner, task: current, response })
+        : await resolveConflict(ws, { adapter, client, owner, conflictId: err.details.conflictId, expectedHash: req.expectedHash, value: payload.value });
+    if (!out.ok) {
+      if (out.supersede) await supersedeTask(deckRoot, id, { owner });
+      throw coded(out.code, out.message, { details: { ...out, supersede: out.supersede === true } });
+    }
+    if (out.task?.status === "completed") return { task: out.task, result: out.task.evidence, replayed: false };
+    const evidence = out.evidence ?? { record: "plan", hash: current.subject.hash };
+    return respondTask(deckRoot, id, req, { invoke: () => ({ evidence }), owner, verify });
+  }
+}
+
+/**
+ * Sync evidence check for `taskRecoverer`: did THIS operation land for exactly
+ * this subject? Core gates say so from their record; a pack deck cannot be read
+ * synchronously here, so it stays pending (never approved by a guess).
+ */
+export function taskEvidenceVerifier({ deckRoot, adapter }) {
+  const ws = wsOf(deckRoot);
+  return (task, response) => {
+    if (isPack(adapter) && task.kind !== "preview-review") return null;
+    const s = task.kind === "preview-review" ? loadReviewState(ws) : loadPlanState(ws);
+    const hash = task.kind === "preview-review" ? s.deckHash : s.planHash;
+    if (s.operationId !== response.operationId || `sha256:${hash}` !== task.subject.hash) return null;
+    return { record: task.kind === "preview-review" ? "state/review.json" : "state/plan-review.json", hash: task.subject.hash };
+  };
+}