molecule-ai/molecule-core
53
0
Fork 2
Code Issues 188 Pull Requests 42 Actions 4 Packages Projects Releases Wiki Activity

RFC: Remove Awareness namespaces — unused ~21-file dead surface #1735

New Issue
Closed
opened 2026-05-23 19:56:44 +00:00 by hongming · 0 comments
hongming commented 2026-05-23 19:56:44 +00:00
Owner
Copy Link
Copy Source

RFC: Remove Awareness namespaces — unused, ~21-file dead surface

Summary

Remove the "Awareness-backed persistence" memory routing surface from the platform. It is plumbed in code and migrations but never wired in any production or staging environment, and the team is committing to a single memory backend (v2 plugin, see #1733).

Phase-1 evidence

What Awareness is, on paper

docs/architecture/memory.md §4 describes: when the runtime receives AWARENESS_URL and AWARENESS_NAMESPACE=workspace:<id>, durable memory tools route through the workspace's awareness namespace instead of the local store. The plumbing exists across workspace-server, the canvas, the provisioner, and one superpowers integration plan.

Where it lives in code

Inventory below (no edits made):

Schema

  • workspace-server/migrations/010_workspace_awareness.sql — adds awareness_namespace TEXT to workspaces.

Go (workspace-server)

  • internal/provisioner/provisioner.go:103-104 — WorkspaceConfig.AwarenessURL, .AwarenessNamespace.
  • internal/provisioner/provisioner.go:707-709 — buildContainerEnv conditionally injects AWARENESS_NAMESPACE + AWARENESS_URL (only when both non-empty).
  • internal/models/workspace.go:20 — Workspace.AwarenessNamespace sql.NullString.
  • internal/handlers/workspace_provision.go:187-230 — seedInitialMemories(awarenessNamespace).
  • internal/handlers/workspace_provision.go:233-241 — workspaceAwarenessNamespace, loadAwarenessNamespace.
  • internal/handlers/workspace_provision.go:297-302 — config wiring; reads AWARENESS_URL from os.Getenv at request time.
  • internal/handlers/workspace_provision_shared.go:90,173,240 — ProvisioningPayload.AwarenessNamespace and call sites.
  • internal/handlers/workspace.go:219,402,645 — INSERT statements include awareness_namespace.
  • internal/handlers/org.go:802, org_import.go:100,166 — more call sites.

Tests

  • internal/provisioner/provisioner_test.go:688-728 — TestBuildContainerEnv_AwarenessOnlyWhenBothSet.
  • internal/handlers/handlers_test.go:367,409-410,437-444 — assertions on response shape + env wiring.
  • internal/handlers/workspace_provision_test.go:20-40,562-690 — TestWorkspaceAwarenessNamespace + seedInitialMemories cases.
  • internal/handlers/workspace_create_name_integration_test.go:133,148,219,234 — INSERT mocks.
  • internal/handlers/workspace_budget_test.go:153 — sqlmock.AnyArg for the column.

Canvas

  • canvas/src/components/tabs/MemoryTab.tsx:18-19,37-262 — reads NEXT_PUBLIC_AWARENESS_URL; renders a full <iframe> block as the bulk of the tab.
  • canvas/src/components/tabs/__tests__/MemoryTab.test.tsx:100-169 — ~6 tests for the awareness dashboard region.

Docs

  • docs/architecture/memory.md §4 (Awareness-backed persistence).
  • docs/architecture/molecule-technical-doc.md (env-var table row + memory section row).
  • docs/agent-runtime/config-format.md, workspace-runtime.md, cli-runtime.md — env-var + routing description.
  • plugins/superpowers/plans/2026-04-08-workspace-awareness-integration.md — integration plan.
  • docs/engineering/postmortem-2026-04-23-boot-event-401.md — minor mention.

Production state

Verified via Railway GraphQL on 2026-05-23 (project molecule-platform, service controlplane):

Env AWARENESS_URL AWARENESS_NAMESPACE NEXT_PUBLIC_AWARENESS_URL
production unset unset unset
staging unset unset unset

Also unset across /etc/molecule-bootstrap/all-credentials.env, secrets.env, agent-secrets.env, /opt/iam/*, and all docker-compose files on the operator host. No production tenant has Awareness wired. The provisioner's buildContainerEnv only injects the vars when both are non-empty, so workspace containers never receive them in practice either.

Conclusion

Awareness is a fully plumbed, fully tested, fully unwired surface. Removing it is a delete-only change with no behavioral impact on any tenant. Keeping it is ongoing maintenance cost (new contributors keep finding it in memory.md and asking how to use it).

Proposal

Single PR, tier:medium-risk (schema change). Scope:

  1. Schema: down migration to drop workspaces.awareness_namespace. Squash with 010 if the squash-window is still open; otherwise add a new forward migration.
  2. Go:
    • Delete WorkspaceConfig.AwarenessURL / .AwarenessNamespace.
    • Delete Workspace.AwarenessNamespace.
    • Remove the AWARENESS_* env injection in provisioner.go:707-709.
    • Drop workspaceAwarenessNamespace, loadAwarenessNamespace, and the awarenessNamespace parameter on seedInitialMemories (update 3 callers: workspace.go, org.go, org_import.go).
    • Drop awareness_namespace from all INSERTs.
    • ProvisioningPayload.AwarenessNamespace removed; update any external SDK consumers (none in molecule-sdk-python per grep, but confirm before merge).
  3. Tests: delete the awareness-specific tests; update INSERT mocks.
  4. Canvas:
    • Remove the iframe block in MemoryTab.tsx:37-262.
    • Remove NEXT_PUBLIC_AWARENESS_URL reads.
    • Delete the 6 awareness tests in MemoryTab.test.tsx.
    • (Note: separate work in #1734 already overhauls MemoryTab to point at v2 — coordinate sequencing.)
  5. Docs:
    • Remove §4 from docs/architecture/memory.md.
    • Update docs/architecture/molecule-technical-doc.md, docs/agent-runtime/config-format.md, workspace-runtime.md, cli-runtime.md.
    • Archive plugins/superpowers/plans/2026-04-08-workspace-awareness-integration.md (move under plugins/superpowers/plans/archived/).

Sequencing vs #1733 and #1734

  • Independent of #1733 (v2 cutover) — Awareness was never an alternative to v2, just a different backend wrapper.
  • Loosely coupled to #1734 (MemoryTab fix): both touch MemoryTab.tsx. Land #1734 first (it changes the fetch URL and re-renders the entry list), then this one (which deletes the iframe block #1734 leaves untouched). Avoids merge conflict.

Stage gates

Dev-sop §SOP-6 Stage A (local boot) + Stage B (staging tenant provision shows no AWARENESS_* in agent container env, no awareness_namespace column referenced). Stage C not required — no user-facing behavior change since the feature was already dark.

Risks

  • External SDK / generated clients: confirm no external consumer (molecule-sdk-python, molecule-cli) reads ProvisioningPayload.AwarenessNamespace before merge. Grep was clean locally; need a cross-repo confirmation.
  • Existing rows: workspaces.awareness_namespace is populated as empty/NULL for all rows today. Migration to drop is safe.

References

  • docs/architecture/memory.md §4
  • workspace-server/migrations/010_workspace_awareness.sql
  • Related: #1733 (memory SSOT), #1734 (Memory tab bug)
# RFC: Remove Awareness namespaces — unused, ~21-file dead surface ## Summary Remove the "Awareness-backed persistence" memory routing surface from the platform. It is plumbed in code and migrations but **never wired in any production or staging environment**, and the team is committing to a single memory backend (v2 plugin, see #1733). ## Phase-1 evidence ### What Awareness is, on paper `docs/architecture/memory.md` §4 describes: when the runtime receives `AWARENESS_URL` and `AWARENESS_NAMESPACE=workspace:<id>`, durable memory tools route through the workspace's awareness namespace instead of the local store. The plumbing exists across workspace-server, the canvas, the provisioner, and one superpowers integration plan. ### Where it lives in code Inventory below (no edits made): **Schema** - `workspace-server/migrations/010_workspace_awareness.sql` — adds `awareness_namespace TEXT` to `workspaces`. **Go (workspace-server)** - `internal/provisioner/provisioner.go:103-104` — `WorkspaceConfig.AwarenessURL`, `.AwarenessNamespace`. - `internal/provisioner/provisioner.go:707-709` — `buildContainerEnv` conditionally injects `AWARENESS_NAMESPACE` + `AWARENESS_URL` (only when both non-empty). - `internal/models/workspace.go:20` — `Workspace.AwarenessNamespace sql.NullString`. - `internal/handlers/workspace_provision.go:187-230` — `seedInitialMemories(awarenessNamespace)`. - `internal/handlers/workspace_provision.go:233-241` — `workspaceAwarenessNamespace`, `loadAwarenessNamespace`. - `internal/handlers/workspace_provision.go:297-302` — config wiring; reads `AWARENESS_URL` from `os.Getenv` at request time. - `internal/handlers/workspace_provision_shared.go:90,173,240` — `ProvisioningPayload.AwarenessNamespace` and call sites. - `internal/handlers/workspace.go:219,402,645` — INSERT statements include `awareness_namespace`. - `internal/handlers/org.go:802`, `org_import.go:100,166` — more call sites. **Tests** - `internal/provisioner/provisioner_test.go:688-728` — `TestBuildContainerEnv_AwarenessOnlyWhenBothSet`. - `internal/handlers/handlers_test.go:367,409-410,437-444` — assertions on response shape + env wiring. - `internal/handlers/workspace_provision_test.go:20-40,562-690` — `TestWorkspaceAwarenessNamespace` + seedInitialMemories cases. - `internal/handlers/workspace_create_name_integration_test.go:133,148,219,234` — INSERT mocks. - `internal/handlers/workspace_budget_test.go:153` — `sqlmock.AnyArg` for the column. **Canvas** - `canvas/src/components/tabs/MemoryTab.tsx:18-19,37-262` — reads `NEXT_PUBLIC_AWARENESS_URL`; renders a full `<iframe>` block as the bulk of the tab. - `canvas/src/components/tabs/__tests__/MemoryTab.test.tsx:100-169` — ~6 tests for the awareness dashboard region. **Docs** - `docs/architecture/memory.md` §4 (Awareness-backed persistence). - `docs/architecture/molecule-technical-doc.md` (env-var table row + memory section row). - `docs/agent-runtime/config-format.md`, `workspace-runtime.md`, `cli-runtime.md` — env-var + routing description. - `plugins/superpowers/plans/2026-04-08-workspace-awareness-integration.md` — integration plan. - `docs/engineering/postmortem-2026-04-23-boot-event-401.md` — minor mention. ### Production state Verified via Railway GraphQL on **2026-05-23** (project `molecule-platform`, service `controlplane`): | Env | `AWARENESS_URL` | `AWARENESS_NAMESPACE` | `NEXT_PUBLIC_AWARENESS_URL` | |---|---|---|---| | production | unset | unset | unset | | staging | unset | unset | unset | Also unset across `/etc/molecule-bootstrap/all-credentials.env`, `secrets.env`, `agent-secrets.env`, `/opt/iam/*`, and all docker-compose files on the operator host. **No production tenant has Awareness wired.** The provisioner's `buildContainerEnv` only injects the vars when both are non-empty, so workspace containers never receive them in practice either. ### Conclusion Awareness is a fully plumbed, fully tested, fully unwired surface. Removing it is a delete-only change with no behavioral impact on any tenant. Keeping it is ongoing maintenance cost (new contributors keep finding it in `memory.md` and asking how to use it). ## Proposal Single PR, `tier:medium-risk` (schema change). Scope: 1. **Schema**: down migration to drop `workspaces.awareness_namespace`. Squash with `010` if the squash-window is still open; otherwise add a new forward migration. 2. **Go**: - Delete `WorkspaceConfig.AwarenessURL` / `.AwarenessNamespace`. - Delete `Workspace.AwarenessNamespace`. - Remove the `AWARENESS_*` env injection in `provisioner.go:707-709`. - Drop `workspaceAwarenessNamespace`, `loadAwarenessNamespace`, and the `awarenessNamespace` parameter on `seedInitialMemories` (update 3 callers: `workspace.go`, `org.go`, `org_import.go`). - Drop `awareness_namespace` from all INSERTs. - `ProvisioningPayload.AwarenessNamespace` removed; update any external SDK consumers (none in `molecule-sdk-python` per grep, but confirm before merge). 3. **Tests**: delete the awareness-specific tests; update INSERT mocks. 4. **Canvas**: - Remove the iframe block in `MemoryTab.tsx:37-262`. - Remove `NEXT_PUBLIC_AWARENESS_URL` reads. - Delete the 6 awareness tests in `MemoryTab.test.tsx`. - (Note: separate work in #1734 already overhauls MemoryTab to point at v2 — coordinate sequencing.) 5. **Docs**: - Remove §4 from `docs/architecture/memory.md`. - Update `docs/architecture/molecule-technical-doc.md`, `docs/agent-runtime/config-format.md`, `workspace-runtime.md`, `cli-runtime.md`. - Archive `plugins/superpowers/plans/2026-04-08-workspace-awareness-integration.md` (move under `plugins/superpowers/plans/archived/`). ## Sequencing vs #1733 and #1734 - Independent of #1733 (v2 cutover) — Awareness was never an alternative to v2, just a different backend wrapper. - Loosely coupled to #1734 (MemoryTab fix): both touch `MemoryTab.tsx`. Land **#1734 first** (it changes the fetch URL and re-renders the entry list), then this one (which deletes the iframe block #1734 leaves untouched). Avoids merge conflict. ## Stage gates Dev-sop §SOP-6 Stage A (local boot) + Stage B (staging tenant provision shows no `AWARENESS_*` in agent container env, no `awareness_namespace` column referenced). Stage C not required — no user-facing behavior change since the feature was already dark. ## Risks - **External SDK / generated clients**: confirm no external consumer (`molecule-sdk-python`, `molecule-cli`) reads `ProvisioningPayload.AwarenessNamespace` before merge. Grep was clean locally; need a cross-repo confirmation. - **Existing rows**: `workspaces.awareness_namespace` is populated as empty/NULL for all rows today. Migration to drop is safe. ## References - `docs/architecture/memory.md` §4 - `workspace-server/migrations/010_workspace_awareness.sql` - Related: #1733 (memory SSOT), #1734 (Memory tab bug)
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area/ci
CI/CD pipeline issues
 do-not-auto-merge
Opt out of autonomous merge-queue merging
 kind/infrastructure
Infrastructure-related issues
 merge-queue
Ready for serialized Gitea merge queue
 merge-queue-hold
Temporarily hold PR in merge queue
 platform/go
Go platform test issues
 release-blocker
Blocks the staging→main promotion / a release
 release-test
security
test-label-sre
tier:high
High risk per dev-sop §SOP-6 — ceo only, 24h cooldown
 tier:low
Low risk per dev-sop §SOP-6 — engineers/managers/ceo can approve
 tier:medium
Medium risk per dev-sop §SOP-6 — managers/ceo can approve
 triage-test
test
 wip
Work in progress — do not auto-merge
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
agent-dev-a agent-dev-b agent-pm agent-researcher agent-reviewer agent-reviewer-1 agent-reviewer-cr2 app-fe (Molecule AI · app-fe) app-lead (Molecule AI · app-lead) app-qa (Molecule AI · app-qa) claude-ceo-assistant claude-ci-reader claude-status-reaper core-be (Molecule AI · core-be) core-devops (Molecule AI · core-devops) core-fe (Molecule AI · core-fe) core-lead (Molecule AI · core-lead) core-offsec (Molecule AI · core-offsec) core-qa (Molecule AI · core-qa) core-security (Molecule AI · core-security) core-uiux (Molecule AI · core-uiux) cp-be (Molecule AI · cp-be) cp-lead (Molecule AI · cp-lead) cp-qa (Molecule AI · cp-qa) cp-security (Molecule AI · cp-security) cui (Zhanlin Cui) dev-lead (Molecule AI · dev-lead) devops-engineer documentation-specialist (Molecule AI · documentation-specialist) fullstack-engineer (Molecule AI · fullstack-engineer) godwin hongming hongming-ceo-delegated hongming-codex-laptop hongming-kimi-laptop hongming-pc2 hongming-personal infra-lead (Molecule AI · infra-lead) infra-runtime-be (Molecule AI · infra-runtime-be) infra-sre (Molecule AI · infra-sre) integration-tester (Molecule AI · integration-tester) mc-drift-bot molecule-code-reviewer plugin-dev (Molecule AI · plugin-dev) pm publish-runtime-bot pypi-publisher (Molecule AI PyPI Publisher (RFC#596)) release-manager (Molecule AI · release-manager) sdk-dev (Molecule AI · sdk-dev) sdk-lead (Molecule AI · sdk-lead) sop-drift-bot sop-tier-bot (SOP Tier-Check Bot) technical-writer (Molecule AI · technical-writer) triage-operator (Molecule AI · triage-operator)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: molecule-ai/molecule-core#1735
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?