chris/OSVauco
1
0
Fork 0
Code Issues 1 Pull Requests Actions 2 Packages Projects Releases Wiki Activity
2fbf54878a
OSVauco/docs/handoffs/EMMA-CANONICALIZATION-2026-09-19.md

12 KiB
Raw Blame History

Emma Canonicalization Handoff

Scope

This handoff begins the controlled, phase-locked Emma canonicalization program.

The program uses one named phase per Gemini session, normally limited to 45–60 minutes. Each phase must start from command-proven Git and runtime state, stay inside its authorized scope, end with tests/diff/status, and stop.

Verified Baseline

  • Repository: ~/OSVauco
  • Branch: feat/opax-domain-decouple
  • Local HEAD: c7c96efd12bb3f3cdcfe9309e7683f0d01c16366
  • Subject: fix(deploy): include MCP requirements in Cloud Build context
  • Date: 2026-09-19T12:39:31+00:00
  • Local worktree status: clean when this handoff was prepared
  • Remote status: local c7c96ef was ahead of origin/feat/opax-domain-decouple before the handoff push

Verified Public Health

  • https://opax.vauco.no/ returned HTTP 200 with valid TLS.
  • opax-mcp authenticated health returned status: ok.
  • The MCP health response reported the expected internal Ollama configuration.
  • The public OPAX site and MCP service are distinct deployed services.

Active Runtime

OPAX MCP

  • Cloud Run service: opax-mcp
  • Active revision: opax-mcp-00200-gcp
  • Traffic: 100%
  • Image:
us-central1-docker.pkg.dev/propane-will-491900-m5/osvauco-repo/opax-mcp@sha256:8687cd7489e789c17f6a56985191d6d924fc03d35d28c78bf94fea8b17b83091

OPAX Web

  • Cloud Run service: opax-web
  • Active revision: opax-web-00014-fnw
  • Traffic: 100%
  • Revision creation: 2026-09-19T00:21:32.201043Z
  • Image:
us-central1-docker.pkg.dev/propane-will-491900-m5/osvauco-repo/opax-web@sha256:27105067393c607d97a4c44fffe54bdf1da6ce7a6dd662e114f039fc04d69892

Failed Acceptance Test

The live OPAX browser chat completed a basic response but failed the same-session conversation-continuity acceptance test.

Turn one

User:
Husk dette testtokenet kun i denne samtalen:
OPAX-EMMA-1909.
Svar bare: registrert

Assistant:
registrert

Turn two

User:
Hva var testtokenet jeg ba deg huske?

Assistant:
Jeg har ikke godkjent VAUCO-kontekst i denne chatten ennå...

This is a failed same-session continuity acceptance test.

Verified Local Source Path

The checked-out source contains the intended same-session history path:

Browser conversation state
→ OPAX Web frontend request history
→ OPAX Web BFF
→ MCP JSON-RPC arguments.history
→ opax-mcp run_emma
→ _normalize_emma_history
→ CanonicalEmma.run
→ _ollama_chat
→ Ollama messages payload

Verified local implementation characteristics:

  • opax-mcp/server.py run_emma passes normalized request history to canonical_emma.run.
  • _normalize_emma_history retains only user and assistant roles.
  • Blank messages are removed.
  • The latest 40 historic messages are retained.
  • opax-mcp/emma_adapter.py CanonicalEmma.run forwards history to its injected chat function.
  • opax-mcp/server.py _ollama_chat places one canonical system prompt first, then history, then the current user prompt.
  • Firestore/Morphic persistence is not part of the current same-session run_emma route.

Unverified Runtime Facts

The following must remain explicitly marked as unverified until supported by runtime payload evidence, deployed-source provenance, or focused tests:

  • Whether active opax-web sends history in the real browser request.
  • Whether active opax-web includes the local history implementation.
  • Whether live Ollama receives the expected second-turn message sequence.
  • Whether the active model uses valid history correctly after receiving it.
  • Firestore/Morphic persistent-memory wiring.
  • INCU ticket storage and execution wiring.
  • Emma access to Gitea/Git context.
  • Perplexity connector correctness.

Architecture Boundaries

  • OPAX Web is the authenticated UI and BFF.
  • opax-mcp is the controlled model and tool gateway.
  • Emma is the canonical runtime/agent.
  • Same-session history, persistent memory, INCU ticketing, Git context, Git writes, and Perplexity connectivity are separate phases.
  • The browser and model must not receive raw credentials, unrestricted terminal access, or direct infrastructure authority.
  • Consequential actions require explicit human approval, resolved targets, structured arguments, audit evidence, and a visible result.
  • Historic client messages may contain only user and assistant roles; historic system and tool roles must not reach the model payload.

Phase Plan

  1. PHASE 0 — Runtime truth baseline.
  2. EMMA-SESSION-001A — No-network session-history regression tests.
  3. EMMA-SESSION-001B — Browser/BFF second-turn history-payload proof.
  4. EMMA-SESSION-001C — Controlled release and live token acceptance.
  5. EMMA-PERSIST-001 — Authenticated, user-scoped Firestore session persistence.
  6. INCU-TICKET-001 — INCU ticket proposal/review workflow; no execution.
  7. EMMA-GIT-READ-001 — Structured read-only Git/Gitea context.
  8. EMMA-PATCH-001 — Patch proposal and allowlisted local validation.
  9. EMMA-GIT-WRITE-001 — Explicit approval-gated Git write lane.
  10. MCP-PERPLEXITY-001 — Separate Perplexity connector repair.

Immediate Next Ticket

EMMA-SESSION-001A

Goal: Add no-network regression coverage for the existing local history path.

Required test coverage:

  1. run_emma normalizes and forwards valid historic user and assistant messages.
  2. Historic system, tool, malformed, blank, and non-string-content entries are excluded.
  3. _ollama_chat creates this exact final ordering:
canonical system prompt
→ validated user/assistant history
→ current user prompt exactly once

Out of scope:

  • Production code changes.
  • Firestore or Morphic persistent memory.
  • Git/Gitea access.
  • INCU ticket execution.
  • Commit, push, build, or deployment.
  • Cloud Run, IAM, secrets, VPC, billing, or DNS changes.

Completion condition: Local no-network tests pass, diff is reviewed, and a human explicitly decides whether to commit.

New Gemini Session Contract

Every Gemini session must:

  1. Work on exactly one named phase.
  2. Begin with raw output from:
    • pwd
    • git branch --show-current
    • git log -1
    • git status --short
  3. Stop if the branch is not feat/opax-domain-decouple.
  4. Stop if unexpected modifications are present.
  5. Use exact source paths and line ranges.
  6. Mark unsupported claims as UNVERIFIED.
  7. Never invent Git SHAs, Cloud Run revisions, image digests, deployments, or test results.
  8. End with actual test results, exact diff, Git status, confirmed facts, unverified facts, and a hard stop.

Commit, push, build, deployment, Firestore writes, Gitea writes, Cloud Run changes, IAM changes, secret changes, VPC changes, and infrastructure actions require separate explicit approval.

EMMA-SESSION-001B Result

Status: PASS

The live OPAX browser same-session conversation-continuity acceptance test passed without a code change, test change, deployment, or runtime configuration change.

Live evidence

Turn 1

User:
Husk dette testtokenet kun i denne samtalen:
OPAX-EMMA-1909.
Svar bare: registrert

Assistant:
Registrert.

Turn 2

User:
Hva var testtokenet jeg ba deg huske?

Assistant:
OPAX-EMMA-1909.

Confirmed

  • Emma preserved and used same-session conversation context through the active OPAX application path.
  • The live application path is functioning for this acceptance test:
opax.vauco.no
→ opax-web
→ opax-mcp
→ CanonicalEmma
→ Ollama
→ OPAX browser response
  • No production code change was justified by this passing result.
  • No OPAX web deployment was justified by this passing result.
  • No MCP deployment was justified by this passing result.

Still unverified

  • Exact browser/BFF JSON payload for the second turn.
  • Exact cause of the earlier failed token test.
  • Browser refresh behavior.
  • New-chat behavior.
  • Cross-session persistence.
  • Firestore/Morphic persistent-memory wiring.
  • INCU ticket workflow wiring.
  • Emma Git/Gitea access.
  • Perplexity connector compatibility.

Next Phase

EMMA-SESSION-001C

Goal: Verify repeatability and clearly distinguish same-session context from persistent memory.

Allowed: Browser-only manual acceptance checks and read-only documentation.

Out of scope:

  • Production code changes.
  • Tests or test-environment changes.
  • Firestore/Morphic memory implementation.
  • Git/Gitea access.
  • INCU ticket execution.
  • Build, deployment, Cloud Run, IAM, secrets, VPC, billing, and DNS changes.

Acceptance checks:

  1. Run a new same-session token test with a different token.
  2. Confirm the second turn returns that new token.
  3. Refresh the browser only after recording whether the same conversation is still visible.
  4. Start a new chat and confirm Emma does not claim to remember the prior chat unless such persistence is explicitly implemented and authorized.
  5. Record each result as PASS, FAIL, or UNVERIFIED.

EMMA-SESSION-001C Result

Status: PASS

This phase verified repeatable same-session context continuity and the intentional boundary between active conversation context and persistent memory.

Check 1 — New same-session continuity

Result: PASS

In a new OPAX conversation:

User:
Husk dette testtokenet kun i denne samtalen:
OPAX-EMMA-SESSION-002.
Svar bare: registrert

Assistant:
Registrert.

User:
Hva var testtokenet jeg ba deg huske?

Assistant:
OPAX-EMMA-SESSION-002.

This confirms repeatable short-term conversation continuity within an active, independent OPAX conversation.

Check 2 — Browser refresh behavior

Result: NOT RESTORED

After one browser refresh with Ctrl+R, the previous conversation was not visible or restored.

This proves only that the current UI does not restore the conversation after refresh. It does not prove or disprove the existence of a backend persistence foundation.

Check 3 — New conversation boundary

Result: PASS

In a new conversation, the user asked whether Emma remembered the token from the previous conversation.

Emma replied that it did not have access to prior conversations or persistent memory in the new chat.

This confirms that Emma does not falsely claim cross-conversation memory and that observed conversation context does not bleed into a new chat.

Conclusion

  • Same-session conversation continuity: PASS.
  • Browser-refresh restoration: not active.
  • New-conversation privacy boundary: PASS.
  • Firestore/Morphic persistent-memory wiring: still unverified.
  • No code, test, deployment, Cloud Run, Firestore, Gitea, IAM, secret, VPC, DNS, or runtime configuration change was justified by this browser-only acceptance phase.

Next Phase

EMMA-PERSIST-001A

Goal: Design and inspect the authenticated, scoped, auditable persistent conversation-memory contract before any implementation.

The next phase must answer:

  1. Which trusted authenticated OPAX user identity reaches the BFF and MCP.
  2. How Conversation, Message, UserScope, WorkspaceScope, and ProjectScope are represented.
  3. Which Firestore collections and fields already exist.
  4. How a conversation can be restored after refresh without allowing cross-user or cross-workspace access.
  5. Retention, deletion, audit, and maximum-context rules.
  6. Whether existing call_emma/Firestore foundation can be reused safely, without blindly enabling its local-emulator path for production browser chat.

Out of scope:

  • Firestore writes.
  • Production code changes.
  • Browser/UI changes.
  • MCP changes.
  • Ticket execution.
  • Git/Gitea access.
  • Commit, push, build, deployment, or infrastructure changes.