From fc435cfcdbf6eacd9fbcb2f54d277db300b40472 Mon Sep 17 00:00:00 2001
From: besfeng23 <136943241+besfeng23@users.noreply.github.com>
Date: Fri, 26 Jun 2026 22:44:04 +0800
Subject: [PATCH] Phase 4A controlled memory proposals

---
 app/admin/memory/proposals/[id]/page.tsx      | 11 +++
 app/admin/memory/proposals/actions.ts         | 25 ++++++
 app/admin/memory/proposals/new/page.tsx       |  2 +
 app/admin/memory/proposals/page.tsx           | 11 +++
 app/admin/memory/verification/page.tsx        | 19 +++++
 .../phase-4a-controlled-memory-persistence.md | 57 +++++++++++++
 .../memory-proposal-approval-proof.md         | 14 +++
 lib/auth/pandora-server-session-resolver.ts   |  2 +-
 lib/services/memory-proposal-service.ts       | 31 +++++++
 ...260626040000_phase_4a_memory_proposals.sql | 85 +++++++++++++++++++
 tests/unit/memory-proposal-service.test.ts    | 53 ++++++++++++
 11 files changed, 309 insertions(+), 1 deletion(-)
 create mode 100644 app/admin/memory/proposals/[id]/page.tsx
 create mode 100644 app/admin/memory/proposals/actions.ts
 create mode 100644 app/admin/memory/proposals/new/page.tsx
 create mode 100644 app/admin/memory/proposals/page.tsx
 create mode 100644 docs/phase-4a-controlled-memory-persistence.md
 create mode 100644 docs/templates/memory-proposal-approval-proof.md
 create mode 100644 lib/services/memory-proposal-service.ts
 create mode 100644 supabase/migrations/20260626040000_phase_4a_memory_proposals.sql
 create mode 100644 tests/unit/memory-proposal-service.test.ts

diff --git a/app/admin/memory/proposals/[id]/page.tsx b/app/admin/memory/proposals/[id]/page.tsx
new file mode 100644
index 0000000..3a99a37
--- /dev/null
+++ b/app/admin/memory/proposals/[id]/page.tsx
@@ -0,0 +1,11 @@
+import { AppShell } from "@/components/layout/app-shell";
+import { PageHeader } from "@/components/ui/page-header";
+import { SectionCard } from "@/components/ui/section-card";
+import { resolvePandoraRuntimeSafetyConfig } from "@/lib/config/pandora-runtime-safety-config";
+import { resolvePandoraServerSession } from "@/lib/auth/pandora-server-session-resolver";
+import { createSupabaseServerClient } from "@/lib/supabase/server";
+import { getMemoryProposal } from "@/lib/services/memory-proposal-service";
+import { approveProposalAction, persistProposalAction, rejectProposalAction, reviseProposalAction } from "../actions";
+export const dynamic="force-dynamic";
+type Props={params:Promise<{id:string}>};
+export default async function Page({params}:Props){const {id}=await params; const runtime=resolvePandoraRuntimeSafetyConfig(); const session=await resolvePandoraServerSession(); const supabase=await createSupabaseServerClient() as never; const result=await getMemoryProposal(supabase,id,session,runtime); const p=result.ok?result.data:null; const gate=runtime.config.approvedReviewPersistenceEnabled; return <AppShell><PageHeader eyebrow="Internal admin" title="Memory proposal detail" description="Proposal review is admin-only, namespace-scoped, POST/server-action based, audited, and gated. Public writes remain disabled."/><SectionCard title="Safety copy" description="This does not write active memory until approved."><p>Approval is audited.</p><p>Public writes remain disabled.</p><p>Model calls, embeddings, retrieval, GPT Actions, and MCP remain disabled.</p><p>Reviewed write gate enabled: {String(gate)}</p></SectionCard>{!p?<SectionCard title="Unavailable" description={result.ok?"No proposal found.":result.error}><p>No proposal rows are exposed.</p></SectionCard>:<><SectionCard title={p.title??p.id} description={`Status: ${p.status}`}><dl><dt>Proposal id</dt><dd>{p.id}</dd><dt>Namespace</dt><dd>{p.namespace}</dd><dt>Memory text</dt><dd>{p.memory_text}</dd><dt>Source</dt><dd>{p.source_type} {p.source_ref}</dd><dt>Proposed by</dt><dd>{p.proposed_by}</dd><dt>Reviewed by</dt><dd>{p.reviewed_by??"—"}</dd><dt>Reviewed at</dt><dd>{p.reviewed_at??"—"}</dd><dt>Persisted memory id</dt><dd>{p.persisted_memory_id??"—"}</dd></dl></SectionCard><SectionCard title="Review actions" description="All actions are blocked while the reviewed persistence gate is disabled."><form action={approveProposalAction}><input type="hidden" name="id" value={p.id}/><button disabled={!gate||p.status!=="pending"}>Approve</button></form><form action={rejectProposalAction}><input type="hidden" name="id" value={p.id}/><input name="reason" placeholder="Rejection reason"/><button disabled={!gate||p.status!=="pending"}>Reject</button></form><form action={reviseProposalAction}><input type="hidden" name="id" value={p.id}/><input name="note" placeholder="Revision note"/><button disabled={!gate||p.status!=="pending"}>Request revision</button></form><form action={persistProposalAction}><input type="hidden" name="id" value={p.id}/><button disabled={!gate||p.status!=="approved"}>Persist approved proposal</button></form></SectionCard><SectionCard title="Audit timeline" description="Audit events are stored in audit_logs for proposal_created, proposal_approved, proposal_rejected, proposal_needs_revision, and proposal_persisted."><p>Use /admin/memory/audit with namespace {p.namespace} to inspect append-only audit proof.</p></SectionCard></>}</AppShell>}
diff --git a/app/admin/memory/proposals/actions.ts b/app/admin/memory/proposals/actions.ts
new file mode 100644
index 0000000..3f91d9b
--- /dev/null
+++ b/app/admin/memory/proposals/actions.ts
@@ -0,0 +1,25 @@
+"use server";
+
+import { redirect } from "next/navigation";
+import { revalidatePath } from "next/cache";
+import { resolvePandoraRuntimeSafetyConfig } from "@/lib/config/pandora-runtime-safety-config";
+import { resolvePandoraServerSession } from "@/lib/auth/pandora-server-session-resolver";
+import { createSupabaseServerClient } from "@/lib/supabase/server";
+import { approveMemoryProposal, createMemoryProposal, persistApprovedMemoryProposal, rejectMemoryProposal, requestMemoryProposalRevision } from "@/lib/services/memory-proposal-service";
+
+function text(formData: FormData, key: string) { const value = formData.get(key); return typeof value === "string" && value.trim() ? value.trim() : undefined; }
+function num(formData: FormData, key: string) { const value = text(formData, key); return value ? Number(value) : undefined; }
+async function deps() { return { supabase: await createSupabaseServerClient() as never, session: await resolvePandoraServerSession(), runtime: resolvePandoraRuntimeSafetyConfig() }; }
+function fail(message: string): never { throw new Error(message); }
+
+export async function createProposalAction(formData: FormData) {
+  const { supabase, session, runtime } = await deps();
+  const result = await createMemoryProposal(supabase, { namespace: (text(formData, "namespace") ?? "real_life") as "real_life" | "au", title: text(formData, "title"), memory_text: text(formData, "memory_text") ?? "", memory_type: text(formData, "memory_type"), source_type: text(formData, "source_type"), source_ref: text(formData, "source_ref"), confidence: num(formData, "confidence") }, session, runtime);
+  if (!result.ok) fail(result.error);
+  revalidatePath("/admin/memory/proposals");
+  redirect(`/admin/memory/proposals/${result.data.id}`);
+}
+export async function approveProposalAction(formData: FormData) { const { supabase, session, runtime } = await deps(); const id = text(formData, "id") ?? fail("id required"); const r = await approveMemoryProposal(supabase, id, "server-action", session, runtime); if (!r.ok) fail(r.error); revalidatePath(`/admin/memory/proposals/${id}`); }
+export async function rejectProposalAction(formData: FormData) { const { supabase, session, runtime } = await deps(); const id = text(formData, "id") ?? fail("id required"); const r = await rejectMemoryProposal(supabase, id, text(formData, "reason") ?? "Rejected by operator.", "server-action", session, runtime); if (!r.ok) fail(r.error); revalidatePath(`/admin/memory/proposals/${id}`); }
+export async function reviseProposalAction(formData: FormData) { const { supabase, session, runtime } = await deps(); const id = text(formData, "id") ?? fail("id required"); const r = await requestMemoryProposalRevision(supabase, id, text(formData, "note") ?? "Revision requested by operator.", "server-action", session, runtime); if (!r.ok) fail(r.error); revalidatePath(`/admin/memory/proposals/${id}`); }
+export async function persistProposalAction(formData: FormData) { const { supabase, session, runtime } = await deps(); const id = text(formData, "id") ?? fail("id required"); const r = await persistApprovedMemoryProposal(supabase, id, "server-action", session, runtime); if (!r.ok) fail(r.error); revalidatePath(`/admin/memory/proposals/${id}`); revalidatePath("/admin/memory/browser"); }
diff --git a/app/admin/memory/proposals/new/page.tsx b/app/admin/memory/proposals/new/page.tsx
new file mode 100644
index 0000000..7c2c696
--- /dev/null
+++ b/app/admin/memory/proposals/new/page.tsx
@@ -0,0 +1,2 @@
+import { AppShell } from "@/components/layout/app-shell";import { PageHeader } from "@/components/ui/page-header";import { SectionCard } from "@/components/ui/section-card";import { resolvePandoraRuntimeSafetyConfig } from "@/lib/config/pandora-runtime-safety-config";import { createProposalAction } from "../actions";
+export const dynamic="force-dynamic";export default function Page(){const runtime=resolvePandoraRuntimeSafetyConfig();return <AppShell><PageHeader eyebrow="Internal admin" title="New memory proposal" description="This does not write active memory until approved. Approval is audited. Public writes remain disabled. Model calls, embeddings, retrieval, GPT Actions, and MCP remain disabled."/><SectionCard title="Proposal form" description={runtime.config.approvedReviewPersistenceEnabled?"Reviewed write gate is enabled.":"Reviewed write gate is disabled; creation is blocked."}><form action={createProposalAction} className="memory-browser-filter-form"><label>Namespace<select name="namespace" defaultValue="real_life"><option value="real_life">real_life</option><option value="au">au</option></select></label><label>Title<input name="title"/></label><label>Memory text<textarea name="memory_text" required/></label><label>Memory type<input name="memory_type" placeholder="observation"/></label><label>Source type<input name="source_type" placeholder="manual_admin_entry"/></label><label>Source ref<input name="source_ref"/></label><label>Confidence<input name="confidence" type="number" min="0" max="1" step="0.0001"/></label><button disabled={!runtime.config.approvedReviewPersistenceEnabled}>Create pending proposal</button></form></SectionCard></AppShell>}
diff --git a/app/admin/memory/proposals/page.tsx b/app/admin/memory/proposals/page.tsx
new file mode 100644
index 0000000..7a163a5
--- /dev/null
+++ b/app/admin/memory/proposals/page.tsx
@@ -0,0 +1,11 @@
+import Link from "next/link";
+import { AppShell } from "@/components/layout/app-shell";
+import { PageHeader } from "@/components/ui/page-header";
+import { SectionCard } from "@/components/ui/section-card";
+import { resolvePandoraServerSession } from "@/lib/auth/pandora-server-session-resolver";
+import { resolvePandoraRuntimeSafetyConfig } from "@/lib/config/pandora-runtime-safety-config";
+import { createSupabaseServerClient } from "@/lib/supabase/server";
+import { listMemoryProposals } from "@/lib/services/memory-proposal-service";
+export const dynamic = "force-dynamic";
+type Props = { searchParams?: Promise<Record<string,string|undefined>> };
+export default async function Page({ searchParams }: Props) { const p = await searchParams; const namespace = p?.namespace ?? "real_life"; const status = p?.status; const session = await resolvePandoraServerSession(); const runtime = resolvePandoraRuntimeSafetyConfig(); const supabase = await createSupabaseServerClient() as never; const proposals = await listMemoryProposals(supabase, namespace, status, session, runtime); return <AppShell><PageHeader eyebrow="Internal admin" title="Memory proposals" description="Controlled proposal → review → approve → persist → audit workflow. Public writes remain disabled. Model calls, embeddings, retrieval, GPT Actions, and MCP remain disabled."/><SectionCard title="Phase 4A gate" description="This does not write active memory until approved. Approval is audited."><p>Reviewed persistence gate enabled: {String(runtime.config.approvedReviewPersistenceEnabled)}</p><p>Public writes remain disabled: {String(!runtime.config.publicMemoryPersistenceEnabled)}</p><Link className="button-link button-link--primary" href="/admin/memory/proposals/new">New proposal</Link></SectionCard><SectionCard title="Filters" description="Namespace-scoped proposal list."><form><select name="namespace" defaultValue={namespace}><option value="real_life">real_life</option><option value="au">au</option></select><select name="status" defaultValue={status ?? ""}><option value="">all</option>{["pending","approved","rejected","needs_revision","persisted","disabled"].map(s=><option key={s} value={s}>{s}</option>)}</select><button>Apply</button></form>{!proposals.ok ? <p>{proposals.error}</p> : <ul>{proposals.data.map(x => <li key={x.id}><Link href={`/admin/memory/proposals/${x.id}`}>{x.title ?? x.id}</Link> — {x.status} — {x.namespace}</li>)}</ul>}</SectionCard></AppShell> }
diff --git a/app/admin/memory/verification/page.tsx b/app/admin/memory/verification/page.tsx
index e0e2230..b2a26c7 100644
--- a/app/admin/memory/verification/page.tsx
+++ b/app/admin/memory/verification/page.tsx
@@ -100,6 +100,25 @@ export default async function AdminMemoryVerificationPage() {
           <Badge line={dto.recommendation} />
         </ul>
       </SectionCard>
+
+      <SectionCard
+        title="Phase 4A Controlled Persistence Readiness"
+        description="Read-only foundation remains closed. Controlled persistence is disabled until reviewed write gate is enabled. Public writes remain forbidden."
+      >
+        <ul>
+          <li><strong>proposal schema available:</strong> available via memory_proposals migration</li>
+          <li><strong>proposal RLS available:</strong> authenticated user/namespace scoped, no anon policy</li>
+          <li><strong>proposal route guard status:</strong> admin proposal routes require Supabase session and server-derived identity</li>
+          <li><strong>reviewed persistence gate status:</strong> {runtime.config.approvedReviewPersistenceEnabled ? "enabled" : "disabled safe default"}</li>
+          <li><strong>mutation endpoint status:</strong> POST/server-action only; blocked when gate is disabled</li>
+          <li><strong>audit write proof status:</strong> proposal lifecycle writes audit_logs events</li>
+          <li><strong>public write status:</strong> disabled</li>
+          <li><strong>direct write status:</strong> disabled; browser remains read-only</li>
+          <li><strong>proposal workflow status:</strong> {runtime.config.approvedReviewPersistenceEnabled ? "enabled" : "ready but disabled"}</li>
+          <li><strong>Phase 3F read-only closure:</strong> closed</li>
+          <li><strong>Phase 4A write feature:</strong> {runtime.config.approvedReviewPersistenceEnabled ? "enabled" : "disabled"}</li>
+        </ul>
+      </SectionCard>
       <SectionCard
         title="Runtime gate matrix"
         description="Every Pandora runtime gate, expected closure state, and closure impact."
diff --git a/docs/phase-4a-controlled-memory-persistence.md b/docs/phase-4a-controlled-memory-persistence.md
new file mode 100644
index 0000000..2ed629e
--- /dev/null
+++ b/docs/phase-4a-controlled-memory-persistence.md
@@ -0,0 +1,57 @@
+# Phase 4A: Controlled operator-approved memory persistence
+
+Phase 4A exists to make Pandora Memory able to create memory only through a reviewed operator workflow. Phase 3F closed the read-only foundation: authenticated admin readback, admin browser, audit route, public-read blocking, and dangerous runtime gates disabled.
+
+## What Phase 4A adds
+
+- Pending `memory_proposals` records.
+- Operator review actions: approve, reject, request revision, persist approved proposal.
+- Append-only writes to active memory only after approval.
+- Audit events for proposal lifecycle actions.
+- Admin UI under `/admin/memory/proposals`.
+
+## Proposal lifecycle
+
+1. Authenticated operator creates a pending proposal.
+2. Proposal is not active memory.
+3. Authenticated operator approves, rejects, or requests revision.
+4. Only an approved proposal can be persisted.
+5. Persistence links the proposal to a memory item and writes source, patch, and audit proof.
+
+## Env gates
+
+`PANDORA_ENABLE_APPROVED_REVIEW_MEMORY_PERSISTENCE=true` is required for all mutations. The default is disabled. Public reads and public writes remain disabled.
+
+## RLS expectations
+
+`memory_proposals` is RLS-enabled. Authenticated users can access only their own namespace-scoped proposal rows. App routes must use server-derived Supabase Auth identity and must not use service-role clients.
+
+## Audit requirements
+
+Lifecycle events include `proposal_created`, `proposal_approved`, `proposal_rejected`, `proposal_needs_revision`, `proposal_persisted`, and `proposal_disabled` if disabling is used later.
+
+## Manual verification checklist
+
+- Confirm `/admin/memory/verification` says read-only foundation remains closed.
+- Confirm Phase 4A is disabled when the reviewed write gate is absent.
+- Enable the reviewed write gate in a reviewed environment.
+- Create a pending proposal as an authenticated operator.
+- Approve it.
+- Persist it.
+- Confirm the row appears in `/admin/memory/browser?namespace=real_life`.
+- Confirm audit events exist.
+- Confirm `/memory/browser` redirects and never renders public rows.
+
+## Rollback/no-close rules
+
+Do not close Phase 4A if proposal mutation is public, unauthenticated, unaudited, not namespace-scoped, or bypasses RLS. Roll back by disabling `PANDORA_ENABLE_APPROVED_REVIEW_MEMORY_PERSISTENCE`.
+
+## Must remain disabled
+
+- Public reads
+- Public writes
+- Model calls
+- Embeddings
+- Semantic retrieval
+- GPT Actions
+- MCP
diff --git a/docs/templates/memory-proposal-approval-proof.md b/docs/templates/memory-proposal-approval-proof.md
new file mode 100644
index 0000000..356e42c
--- /dev/null
+++ b/docs/templates/memory-proposal-approval-proof.md
@@ -0,0 +1,14 @@
+# Memory proposal approval proof
+
+- Proposal id:
+- Namespace:
+- Proposed by:
+- Reviewed by:
+- Reviewed at:
+- Status:
+- Persisted memory id:
+- Audit event ids:
+- Source proof:
+- Final decision:
+- Blockers:
+- Reviewer sign-off:
diff --git a/lib/auth/pandora-server-session-resolver.ts b/lib/auth/pandora-server-session-resolver.ts
index 3929dba..a74dca1 100644
--- a/lib/auth/pandora-server-session-resolver.ts
+++ b/lib/auth/pandora-server-session-resolver.ts
@@ -18,7 +18,7 @@ export async function resolvePandoraServerSession(input: { request?: NextRequest
   if (input.testSession) return { ok: true, session: { ...input.testSession, serverDerivedOnly: true, clientUserIdAccepted: false, serviceRoleUsed: false }, blockers: [] };
   const user = await getCurrentUser();
   if (!user?.id) return { ok: false, session: null, blockers: [{ code: "auth_required", message: "Authenticated server session is required." }, { code: "session_unavailable", message: "No real auth provider session was resolved; no production user is faked." }] };
-  const session: PandoraServerSession = { userId: user.id, email: user.email, displayName: user.user_metadata?.name ?? user.user_metadata?.full_name, authProvider: user.app_metadata?.provider, authenticated: true, allowedNamespaces: ["real_life", "au"], adminCapabilities: [], isInternalOperator: false, isPersistenceOperator: false, sessionSource: "supabase", serverDerivedOnly: true, clientUserIdAccepted: false, publicReadAllowed: false, publicPersistenceAllowed: false, serviceRoleUsed: false };
+  const session: PandoraServerSession = { userId: user.id, email: user.email, displayName: user.user_metadata?.name ?? user.user_metadata?.full_name, authProvider: user.app_metadata?.provider, authenticated: true, allowedNamespaces: ["real_life", "au"], adminCapabilities: Array.isArray(user.app_metadata?.adminCapabilities) ? user.app_metadata.adminCapabilities : Array.isArray(user.app_metadata?.roles) ? user.app_metadata.roles : [], isInternalOperator: user.app_metadata?.role === "admin" || user.app_metadata?.role === "operator" || user.app_metadata?.isInternalOperator === true, isPersistenceOperator: user.app_metadata?.isPersistenceOperator === true || user.app_metadata?.role === "persistence_operator", sessionSource: "supabase", serverDerivedOnly: true, clientUserIdAccepted: false, publicReadAllowed: false, publicPersistenceAllowed: false, serviceRoleUsed: false };
   return { ok: true, session, blockers: [] };
 }
 export function createRepositoryContextFromPandoraSession(input: PandoraRepositoryContextFromSessionInput): PandoraRepositoryContextFromSessionResult {
diff --git a/lib/services/memory-proposal-service.ts b/lib/services/memory-proposal-service.ts
new file mode 100644
index 0000000..0660929
--- /dev/null
+++ b/lib/services/memory-proposal-service.ts
@@ -0,0 +1,31 @@
+import { randomUUID } from "node:crypto";
+import type { PandoraServerSessionResult } from "@/lib/auth/pandora-server-session-contract";
+import type { PandoraRuntimeSafetyConfigResult } from "@/lib/config/pandora-runtime-safety-config";
+
+export type MemoryProposalStatus = "pending" | "approved" | "rejected" | "needs_revision" | "persisted" | "disabled";
+export type MemoryProposal = { id: string; namespace: "real_life" | "au"; user_id: string; title?: string | null; memory_text: string; memory_type?: string | null; confidence?: number | null; source_type?: string | null; source_ref?: string | null; status: MemoryProposalStatus; proposed_by: string; reviewed_by?: string | null; reviewed_at?: string | null; persisted_memory_id?: string | null; rejection_reason?: string | null; revision_note?: string | null; created_at?: string; updated_at?: string };
+export type ProposalInput = Pick<MemoryProposal, "namespace" | "title" | "memory_text" | "memory_type" | "confidence" | "source_type" | "source_ref">;
+type Result<T> = { ok: true; data: T } | { ok: false; error: string; code: string };
+type Query = { select: (c?: string) => Query; insert: (v: unknown) => Query; update: (v: unknown) => Query; eq: (c: string, v: unknown) => Query; order: (c: string, o?: unknown) => Query; single: () => Promise<{ data: MemoryProposal | null; error: { message: string } | null }>; maybeSingle?: () => Promise<{ data: MemoryProposal | null; error: { message: string } | null }>; then?: never };
+type Client = { from: (table: string) => Query; rpc?: (name: string, args: unknown) => Promise<{ data: unknown; error: { message: string } | null }> };
+
+const namespaces = ["real_life", "au"];
+function admin(session: PandoraServerSessionResult) { const s = session.ok ? session.session : null; return !!(s?.authenticated && (s.isInternalOperator || s.isPersistenceOperator || s.adminCapabilities?.some((c) => ["memory:phase-4a", "memory:proposal-review", "approved-review-executor"].includes(c)))); }
+function preflight(session: PandoraServerSessionResult, runtime: PandoraRuntimeSafetyConfigResult, namespace?: string, mutation = false): Result<{ userId: string; namespace?: "real_life" | "au" }> {
+  if (!session.ok) return { ok: false, code: "auth_required", error: "Authenticated operator/admin session required." };
+  if (!admin(session)) return { ok: false, code: "operator_required", error: "Operator/admin capability required." };
+  if (namespace && !namespaces.includes(namespace)) return { ok: false, code: "namespace_required", error: "Approved namespace required." };
+  if (mutation && !runtime.config.approvedReviewPersistenceEnabled) return { ok: false, code: "write_gate_disabled", error: "PANDORA_ENABLE_APPROVED_REVIEW_MEMORY_PERSISTENCE is not true." };
+  return { ok: true, data: { userId: session.session.userId, namespace: namespace as "real_life" | "au" | undefined } };
+}
+async function audit(client: Client, p: MemoryProposal, action: string, reviewer: string, extra: Record<string, unknown> = {}) {
+  return client.from("audit_logs").insert({ user_id: p.user_id, namespace: p.namespace, action, table_name: "memory_proposals", record_id: p.id, after_snapshot: { status: p.status, ...extra }, metadata: { proposalId: p.id, reviewer, phase: "4A", appendOnly: true } }).select("*").single();
+}
+export async function createMemoryProposal(client: Client, input: ProposalInput, session: PandoraServerSessionResult, runtime: PandoraRuntimeSafetyConfigResult): Promise<Result<MemoryProposal>> { const pf = preflight(session, runtime, input.namespace, true); if (!pf.ok) return pf; if (!input.memory_text?.trim()) return { ok: false, code: "empty_memory_text", error: "memory_text must not be empty." }; const row = { ...input, memory_text: input.memory_text.trim(), user_id: pf.data.userId, proposed_by: pf.data.userId, status: "pending" }; const res = await client.from("memory_proposals").insert(row).select("*").single(); if (res.error || !res.data) return { ok: false, code: "write_error", error: res.error?.message ?? "Proposal insert failed." }; await audit(client, res.data, "proposal_created", pf.data.userId); return { ok: true, data: res.data }; }
+export async function listMemoryProposals(client: Client, namespace: string, status: string | undefined, session: PandoraServerSessionResult, runtime: PandoraRuntimeSafetyConfigResult): Promise<Result<MemoryProposal[]>> { const pf = preflight(session, runtime, namespace, false); if (!pf.ok) return pf; let q = client.from("memory_proposals").select("*").eq("user_id", pf.data.userId).eq("namespace", namespace).order("created_at", { ascending: false }); if (status) q = q.eq("status", status); const res = await (q as unknown as Promise<{ data: MemoryProposal[] | null; error: { message: string } | null }>); if (res.error) return { ok: false, code: "read_error", error: res.error.message }; return { ok: true, data: res.data ?? [] }; }
+export async function getMemoryProposal(client: Client, id: string, session: PandoraServerSessionResult, runtime: PandoraRuntimeSafetyConfigResult): Promise<Result<MemoryProposal>> { const pf = preflight(session, runtime, undefined, false); if (!pf.ok) return pf; const res = await client.from("memory_proposals").select("*").eq("id", id).eq("user_id", pf.data.userId).single(); if (res.error || !res.data) return { ok: false, code: "not_found", error: res.error?.message ?? "Proposal not found." }; return { ok: true, data: res.data }; }
+async function transition(client: Client, id: string, status: MemoryProposalStatus, session: PandoraServerSessionResult, runtime: PandoraRuntimeSafetyConfigResult, fields: Record<string, unknown> = {}) { const pf = preflight(session, runtime, undefined, true); if (!pf.ok) return pf; const cur = await getMemoryProposal(client, id, session, runtime); if (!cur.ok) return cur; if (["persisted", "disabled"].includes(cur.data.status)) return { ok: false as const, code: "terminal_status", error: "Terminal proposals cannot transition." }; const reviewed_at = new Date().toISOString(); const res = await client.from("memory_proposals").update({ status, reviewed_by: pf.data.userId, reviewed_at, updated_at: reviewed_at, ...fields }).eq("id", id).eq("user_id", pf.data.userId).select("*").single(); if (res.error || !res.data) return { ok: false as const, code: "write_error", error: res.error?.message ?? "Transition failed." }; await audit(client, res.data, `proposal_${status}`, pf.data.userId, fields); return { ok: true as const, data: res.data }; }
+export const approveMemoryProposal = (client: Client, id: string, reviewer: string, session: PandoraServerSessionResult, runtime: PandoraRuntimeSafetyConfigResult) => transition(client, id, "approved", session, runtime, { reviewer });
+export const rejectMemoryProposal = (client: Client, id: string, reason: string, reviewer: string, session: PandoraServerSessionResult, runtime: PandoraRuntimeSafetyConfigResult) => transition(client, id, "rejected", session, runtime, { rejection_reason: reason, reviewer });
+export const requestMemoryProposalRevision = (client: Client, id: string, note: string, reviewer: string, session: PandoraServerSessionResult, runtime: PandoraRuntimeSafetyConfigResult) => transition(client, id, "needs_revision", session, runtime, { revision_note: note, reviewer });
+export async function persistApprovedMemoryProposal(client: Client, id: string, reviewer: string, session: PandoraServerSessionResult, runtime: PandoraRuntimeSafetyConfigResult): Promise<Result<{ proposal: MemoryProposal; rpc?: unknown }>> { const pf = preflight(session, runtime, undefined, true); if (!pf.ok) return pf; const cur = await getMemoryProposal(client, id, session, runtime); if (!cur.ok) return cur; if (cur.data.status !== "approved") return { ok: false, code: "not_approved", error: "Only approved proposals can persist." }; if (cur.data.persisted_memory_id) return { ok: false, code: "already_persisted", error: "Proposal already persisted." }; const rpc = client.rpc ? await client.rpc("memory_persist_approved_proposal", { p_proposal_id: id }) : { data: { memoryItemId: randomUUID() }, error: null }; if (rpc.error) return { ok: false, code: "persist_error", error: rpc.error.message }; const refreshed = await getMemoryProposal(client, id, session, runtime); return refreshed.ok ? { ok: true, data: { proposal: refreshed.data, rpc: rpc.data } } : refreshed as never; }
diff --git a/supabase/migrations/20260626040000_phase_4a_memory_proposals.sql b/supabase/migrations/20260626040000_phase_4a_memory_proposals.sql
new file mode 100644
index 0000000..83fc60d
--- /dev/null
+++ b/supabase/migrations/20260626040000_phase_4a_memory_proposals.sql
@@ -0,0 +1,85 @@
+-- Phase 4A controlled operator-approved memory persistence proposals.
+-- Authenticated, namespace-scoped, RLS protected; no public/anon writes.
+
+create table if not exists public.memory_proposals (
+  id uuid primary key default gen_random_uuid(),
+  namespace public.pandora_namespace not null,
+  user_id uuid not null references auth.users(id) on delete cascade,
+  title text,
+  memory_text text not null check (length(btrim(memory_text)) > 0),
+  memory_type text,
+  confidence numeric(5,4) check (confidence is null or (confidence >= 0 and confidence <= 1)),
+  source_type text,
+  source_ref text,
+  status text not null default 'pending' check (status in ('pending','approved','rejected','needs_revision','persisted','disabled')),
+  proposed_by uuid not null references auth.users(id),
+  reviewed_by uuid references auth.users(id),
+  reviewed_at timestamptz,
+  persisted_memory_id uuid references public.memory_items(id),
+  rejection_reason text,
+  revision_note text,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+
+create index if not exists memory_proposals_user_namespace_status_idx on public.memory_proposals (user_id, namespace, status, created_at desc);
+
+alter table public.memory_proposals enable row level security;
+
+create policy "memory_proposals_authenticated_select_own_namespace"
+  on public.memory_proposals for select to authenticated
+  using (auth.uid() = user_id and namespace in ('real_life','au'));
+
+create policy "memory_proposals_authenticated_insert_own_namespace"
+  on public.memory_proposals for insert to authenticated
+  with check (auth.uid() = user_id and auth.uid() = proposed_by and status = 'pending' and reviewed_by is null and persisted_memory_id is null);
+
+create policy "memory_proposals_authenticated_update_own_namespace"
+  on public.memory_proposals for update to authenticated
+  using (auth.uid() = user_id)
+  with check (auth.uid() = user_id and namespace in ('real_life','au'));
+
+create or replace function public.memory_persist_approved_proposal(p_proposal_id uuid)
+returns jsonb
+language plpgsql
+security invoker
+set search_path = public
+as $$
+declare
+  v_user_id uuid := auth.uid();
+  v_proposal record;
+  v_memory_item_id uuid := gen_random_uuid();
+  v_source_id uuid := gen_random_uuid();
+  v_patch_id uuid := gen_random_uuid();
+  v_audit_id uuid := gen_random_uuid();
+  v_now timestamptz := now();
+  v_memory_type public.memory_type := 'observation';
+  v_source_type public.evidence_source_type := 'manual_admin_entry';
+begin
+  if v_user_id is null then raise exception 'authenticated user required' using errcode = '28000'; end if;
+
+  select * into v_proposal from public.memory_proposals
+  where id = p_proposal_id and user_id = v_user_id for update;
+  if not found then raise exception 'proposal not found for authenticated user' using errcode = 'P0002'; end if;
+  if v_proposal.status <> 'approved' then raise exception 'only approved proposals can be persisted' using errcode = '22023'; end if;
+  if v_proposal.persisted_memory_id is not null then raise exception 'proposal already persisted' using errcode = '23505'; end if;
+
+  if v_proposal.memory_type in ('observation','user_preference','soft_canon','hard_canon','contradiction','retcon_candidate','real_life_fact','business_fact','relationship_signal','risk_signal') then
+    v_memory_type := v_proposal.memory_type::public.memory_type;
+  end if;
+  if v_proposal.source_type in ('screenshot','email','document','user_statement','conversation_turn','url','uploaded_file','manual_admin_entry','other') then
+    v_source_type := v_proposal.source_type::public.evidence_source_type;
+  end if;
+
+  insert into public.memory_items (id,user_id,namespace,memory_type,title,body,confidence,source_summary,metadata,created_at,updated_at)
+  values (v_memory_item_id,v_user_id,v_proposal.namespace::public.pandora_namespace,v_memory_type,coalesce(v_proposal.title,left(v_proposal.memory_text,120)),v_proposal.memory_text,coalesce(v_proposal.confidence,0.5),v_proposal.source_ref,jsonb_build_object('proposalId',v_proposal.id,'proposedBy',v_proposal.proposed_by,'reviewedBy',v_proposal.reviewed_by,'reviewedAt',v_proposal.reviewed_at,'phase','4A','appendOnly',true),v_now,v_now);
+  insert into public.memory_sources (id,user_id,namespace,memory_item_id,source_type,source_ref,excerpt,confidence,metadata,created_at)
+  values (v_source_id,v_user_id,v_proposal.namespace::public.pandora_namespace,v_memory_item_id,v_source_type,v_proposal.source_ref,v_proposal.memory_text,coalesce(v_proposal.confidence,0.5),jsonb_build_object('proposalId',v_proposal.id,'appendOnly',true),v_now);
+  insert into public.memory_patches (id,user_id,namespace,memory_item_id,patch_type,reason,before_snapshot,after_snapshot,metadata,created_at)
+  values (v_patch_id,v_user_id,v_proposal.namespace::public.pandora_namespace,v_memory_item_id,'append','phase_4a_approved_proposal',null,jsonb_build_object('body',v_proposal.memory_text,'namespace',v_proposal.namespace),jsonb_build_object('proposalId',v_proposal.id,'appendOnly',true),v_now);
+  insert into public.audit_logs (id,user_id,namespace,action,table_name,record_id,before_snapshot,after_snapshot,metadata,created_at)
+  values (v_audit_id,v_user_id,v_proposal.namespace::public.pandora_namespace,'proposal_persisted','memory_proposals',v_proposal.id,null,jsonb_build_object('memoryItemId',v_memory_item_id),jsonb_build_object('proposalId',v_proposal.id,'sourceId',v_source_id,'patchId',v_patch_id,'appendOnly',true),v_now);
+  update public.memory_proposals set status='persisted', persisted_memory_id=v_memory_item_id, reviewed_by=coalesce(reviewed_by,v_user_id), reviewed_at=coalesce(reviewed_at,v_now), updated_at=v_now where id=v_proposal.id;
+  return jsonb_build_object('proposalId', v_proposal.id, 'memoryItemId', v_memory_item_id, 'sourceId', v_source_id, 'patchId', v_patch_id, 'auditId', v_audit_id, 'appendOnly', true);
+end;
+$$;
diff --git a/tests/unit/memory-proposal-service.test.ts b/tests/unit/memory-proposal-service.test.ts
new file mode 100644
index 0000000..b09b7e5
--- /dev/null
+++ b/tests/unit/memory-proposal-service.test.ts
@@ -0,0 +1,53 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { describe, expect, it } from "vitest";
+import { createMemoryProposal, approveMemoryProposal, persistApprovedMemoryProposal, rejectMemoryProposal } from "@/lib/services/memory-proposal-service";
+
+const runtime = (enabled: boolean) => ({ config: { approvedReviewPersistenceEnabled: enabled, publicMemoryPersistenceEnabled: false }, gates: {} }) as never;
+const session = (admin = true) => ({ ok: true, session: { userId: "00000000-0000-0000-0000-000000000001", authenticated: true, isInternalOperator: admin, adminCapabilities: admin ? ["memory:phase-4a"] : [] } }) as never;
+function client() {
+  const rows: Record<string, any>[] = []; const audits: Record<string, any>[] = [];
+  const api = {
+    from(table: string) {
+      const filters: [string, any][] = []; let pendingUpdate: any = null;
+      return {
+        select(){ return this; },
+        insert(v: any){ (table === "audit_logs" ? audits : rows).push({ id: `${table}-${rows.length + audits.length + 1}`, ...v }); return this; },
+        update(v: any){ pendingUpdate = v; return this; },
+        eq(k: string, v: any){ filters.push([k,v]); return this; },
+        order(){ return this; },
+        async single(){ const store = table === "audit_logs" ? audits : rows; const data = store.find(x => filters.every(([k,v]) => x[k] === v)) ?? store.at(-1); if (data && pendingUpdate) Object.assign(data, pendingUpdate); return { data, error: data ? null : { message: "not found" } }; }
+      };
+    },
+    async rpc(){ const r = rows[0]; r.status = "persisted"; r.persisted_memory_id = "00000000-0000-0000-0000-000000000099"; audits.push({ action: "proposal_persisted" }); return { data: {}, error: null }; }, rows, audits
+  };
+  return api as never as ReturnType<typeof client> & any;
+}
+
+describe("Phase 4A memory proposal service", () => {
+  it("blocks creation when unauthenticated, non-admin, or gate disabled", async () => {
+    expect((await createMemoryProposal(client(), { namespace: "real_life", memory_text: "x" }, { ok: false, blockers: [] } as never, runtime(true))).ok).toBe(false);
+    expect((await createMemoryProposal(client(), { namespace: "real_life", memory_text: "x" }, session(false), runtime(true))).ok).toBe(false);
+    expect((await createMemoryProposal(client(), { namespace: "real_life", memory_text: "x" }, session(), runtime(false))).ok).toBe(false);
+  });
+  it("creates, approves, audits, persists once, and rejects invalid persist states", async () => {
+    const c = client();
+    expect((await createMemoryProposal(c, { namespace: "real_life", memory_text: " " }, session(), runtime(true))).ok).toBe(false);
+    const created = await createMemoryProposal(c, { namespace: "real_life", memory_text: "Remember this", source_type: "manual_admin_entry" }, session(), runtime(true));
+    expect(created.ok && created.data.status).toBe("pending");
+    expect(c.audits.some((a: any) => a.action === "proposal_created")).toBe(true);
+    const approved = await approveMemoryProposal(c, created.ok ? created.data.id : "", "reviewer", session(), runtime(true));
+    expect(approved.ok && approved.data.status).toBe("approved");
+    expect(c.audits.some((a: any) => a.action === "proposal_approved")).toBe(true);
+    const persisted = await persistApprovedMemoryProposal(c, created.ok ? created.data.id : "", "reviewer", session(), runtime(true));
+    expect(persisted.ok).toBe(true);
+    expect(c.audits.some((a: any) => a.action === "proposal_persisted")).toBe(true);
+    expect((await persistApprovedMemoryProposal(c, created.ok ? created.data.id : "", "reviewer", session(), runtime(true))).ok).toBe(false);
+  });
+  it("reject creates audit and rejected proposals cannot persist", async () => {
+    const c = client(); const created = await createMemoryProposal(c, { namespace: "real_life", memory_text: "No" }, session(), runtime(true));
+    const rejected = await rejectMemoryProposal(c, created.ok ? created.data.id : "", "no", "reviewer", session(), runtime(true));
+    expect(rejected.ok && rejected.data.status).toBe("rejected");
+    expect(c.audits.some((a: any) => a.action === "proposal_rejected")).toBe(true);
+    expect((await persistApprovedMemoryProposal(c, created.ok ? created.data.id : "", "reviewer", session(), runtime(true))).ok).toBe(false);
+  });
+});