RFC-64 M1 1/2: make Edge CG sync explicitly on-demand

[branarakic]

M1 stack

This is PR 1 of 2 in the RFC-64 M1 activation stack.

1. This PR: explicit Edge synchronization lifetime (on-demand vs always-on)
2. RFC-64 M1 2/2: activate selected public catalogs #2090: selected-public RFC-64 activation, producer allowlisting, bootstrap wiring, and applied-head status

#2076 remains an independent public-SWM convergence fix. Once it is final, this two-PR stack will be restacked on its exact testnet-canary head and validated together before canary deployment.

Exact stack provenance

• Base: testnet-canary at 84c2d1bb8e7ad812092648e36adde05ec7365e82
• Head: d946ff89cefe47b7edd32f8b0fa21cd519d560f1
• The focused validation below was rerun after the canary restack and shutdown-admission integration fix; live GitHub CI on this exact head remains authoritative.

User impact

Edge browsing is selective by default:

• Opening or subscribing to a public Context Graph from the UI defaults to on demand. It remains active for this process but is not silently restored after restart.
• The UI exposes Keep synchronized after restart for users who want continuous synchronization.
• dkg subscribe <cg> is on demand; dkg subscribe <cg> --save is always on.
• Opening a graph that is already always on never downgrades the operator's existing choice.
• Operations that establish durable local intent—create, register, publish, approved join, configured bootstrap, or rehydration—explicitly use always-on and survive restart.

This prevents ordinary browsing from turning every graph ever opened into permanent background work without breaking durable authoring and membership flows.

Operator and compatibility impact

• Existing persisted subscriptions still mean always-on and rehydrate as before.
• Internal legacy/durable call sites now pass always-on explicitly rather than relying on an ambiguous omitted mode.
• POST /api/context-graph/subscribe and legacy POST /api/subscribe accept syncMode: "on-demand" | "always-on" and return the mode actually applied by the agent.
• Unknown modes fail with HTTP 400 before state changes.
• A Core StorageACK hosting obligation remains restart-durable even if the same CG was opened on demand. Host-only durable state is projected directly into a subscription record; it does not manufacture a fake live member subscription.
• No database or configuration migration is required.

Before

Previously every successful subscribe request became restart-durable, including a graph opened for one UI session.

sequenceDiagram
    actor User
    participant Client as UI or CLI
    participant Agent
    participant Store as Subscription store

    User->>Client: Open public CG A
    Client->>Agent: Subscribe(CG A)
    Agent->>Store: Persist active member record
    Agent-->>Client: Catch-up queued

    Note over Agent,Store: Node restarts
    Agent->>Store: Restore CG A
    Agent->>Agent: Resume background synchronization

Loading

After

Browsing stays process-local, while authoring, membership, and explicit operator choices remain durable. Core hosting is persisted independently from Edge-style member intent.

sequenceDiagram
    actor User
    participant Client as UI or CLI
    participant Agent
    participant Store as Subscription store

    alt Browse or open CG
        User->>Client: Open public CG A
        Client->>Agent: Subscribe(CG A, on-demand)
        Agent-->>Client: Applied mode = on-demand
        Note over Agent,Store: No durable member record
    else Create, register, publish, join, or explicit save
        User->>Client: Perform durable graph operation
        Client->>Agent: Subscribe(CG A, always-on)
        Agent->>Store: Persist active member record
        Agent-->>Client: Applied mode = always-on
    end

    opt Core signs StorageACK
        Agent->>Store: Persist independent host-only record
    end

    Note over Agent,Store: Node restarts
    Agent->>Store: Restore durable records only

Loading

Implementation notes

• ContextGraphSyncMode is public runtime state; persistence-row presence continues to mean always on.
• Runtime subscriptions and durable projections are separate concepts. Host-only persistence builds ContextGraphSubscriptionRecord directly from actual state and policy.
• The agent owns effective-mode resolution and returns the applied mode, so clients render server-normalized truth.
• Membership-store and subscription-store writes are both suppressed for on-demand member intent and enabled on explicit promotion.
• Every production subscribe caller was audited: only user-facing browse/subscribe entry points retain requested on-demand semantics.

Non-goals

• No automatic in-process idle eviction; an on-demand graph remains active until restart or explicit unsubscribe.
• No change to private membership/join durability.
• No Core all-public scheduler or adaptive concurrency changes; those are later stack PRs.
• No change to RFC-64 catalog selection or convergence logic.

Validation

• Agent build, public type tests, and package-root export test: pass.
• Combined agent lifecycle/discovery/private-bootstrap/core-registration suites: 134/134 pass.
• Additional agent default-config lane: 27/27 pass.
• CLI route/API/command/bootstrap focused suites: 238/238 pass.
• Shutdown telemetry and lifetime-promotion integration suite: 37/37 pass.
• Node UI interaction and API suites: 66/66 pass.
• Full dependency and CLI build chains: pass.
• Live GitHub review and CI status remain the merge-readiness source of truth.
• git diff --check: pass.

Review focus

1. Browse intent stays process-local.
2. Durable create/register/publish/join/bootstrap intent is explicit and restart-safe.
3. On-demand state cannot leak into either durable membership store.
4. Core hosting remains durable without restoring on-demand member intent.
5. CLI/UI output reflects the server-applied mode.