coord: Web-to-CLI realtime sync contract v1

[YoneRai12]

[SYNC-CONTRACT-REQUEST-V1]

Public-safe coordination issue for Web/cloud ↔ CLI/Local realtime conversation sync.

Context:

• StatusSnapshot v1 integration has Public and StatusWEB final evidence in coord: StatusSnapshot v1 cross-repo integration #549.
• YonerAIWEB has merged a noindex /chat staging shell in its private Web lane.
• This issue requests the Public-owned [SYNC-PROPOSAL-V1] schema/version and acceptance rules before YonerAIWEB or AWS implements live sync clients against Firestore.

YonerAIWEB current status:

• /chat shell exists only as noindex staging UI.
• It uses fixture metadata only and performs no network fetch.
• It is not [YONERAIWEB-SYNC-CLIENT-READY].
• It does not claim live Firestore, live AWS body fetch, production cloud, production login, production API, production Discord, or provider shared traffic.

Required Public proposal content:

• schema/version for conversation metadata projection
• schema/version for message metadata without body
• body-free SyncEvent shape
• cursor/version/reconnect semantics
• account/session scope fields and fail-closed behavior
• sync policy display states: local_only, cloud_to_local, bidirectional_explicit, paused, plus diverged/local-extended if accepted
• provider data policy projection and explicit provider-sharing consent model
• approval display projection without approval authority
• status/module/audit projection boundaries
• forbidden fields list: raw body, raw audit, token/key/secret, private runtime details, internal hostnames, local paths, worker identity
• test vectors for body exclusion, account mismatch, duplicate events, stale projections, direct policy/approval mutation rejection

YonerAIWEB implementation gate:

• Wait for [SYNC-PROPOSAL-V1].
• Reply [YONERAIWEB-SYNC-ACK] with Web rendering/auth/body-fetch/accessibility/offline/provider-consent needs.
• Wait for [SYNC-CONTRACT-ACCEPTED].
• Wait for [AWS-SYNC-RUNTIME-READY] before live listener/body-fetch implementation and Web-to-CLI E2E.

Non-claims:

• No production deploy.
• No production cloud/login/API/Oracle/cloud/Discord claim.
• No OpenAI shared traffic claim.
• No raw message body in Firestore.
• No raw audit in Firestore.
• No direct Web client mutation of sync policy or approval decisions in Firestore.

[YoneRai12]

[RATE-RESTORED-RESUME]

Owner says Codex/code-review rate is restored. Public coordination lanes should resume.

Immediate instruction for Codex lanes watching this issue:

• Re-check open/merged PR reviews, review threads, issue comments, and CI.
• Fix legitimate P1/P2/P3/medium/high comments with tests; record non-actionable comments with reasons.
• Keep public-safe boundaries: no secrets, no private AWS/Web details, no unsupported production cloud/login/API/Discord/OpenAI shared-traffic claims.
• Continue toward the Web-to-CLI realtime sync contract only after review debt is clear.

YonerAIWEB current state: private Web lane review debt is cleared on master, PR #3 merged, master CI success. Live listener remains gated on [SYNC-CONTRACT-ACCEPTED] and [AWS-SYNC-RUNTIME-READY].

[YoneRai12]

[SYNC-PROPOSAL-V1] YonerAI Realtime Sync Contract 0.1

Status: proposal for issue #552 ACK
Owner: Public YonerAI contract lane
Schema version: yonerai.realtime_sync.v1
Date: 2026-06-20

This contract defines the public Web-to-CLI realtime sync projection. It is a
metadata-only projection contract. It does not implement production cloud sync,
production Google login, production Oracle, provider execution, or arbitrary
local file/tool access.

Source Priority

1. Public contract in this file and issue coord: Web-to-CLI realtime sync contract v1 #552.
2. AWS staging implementation ACK.
3. YonerAIWEB staging implementation ACK.
4. Older design docs and Codex summaries.

If AWS/Web behavior differs from this contract, the runtime must pause or reject
the incompatible event instead of guessing.

Transport Boundary

Firestore, or any future realtime projection bus, carries metadata only.

Allowed:

• account-scoped conversation/message identifiers
• event type
• sync policy
• cursor and sequence metadata
• body reference
• projection version
• provider-consent reference
• safe audit reference

Forbidden:

• message body
• raw prompt or provider output
• local memory content
• local file content or file bytes
• local node payload
• provider keys or token-like values
• Google access token, ID token, refresh token, auth code
• internal hostnames, IPs, paths, ARNs, worker identity, account email
• raw audit details
• approval authority mutation from the projection bus

The CLI must fetch message body only from authenticated AWS official API using
the body_ref after validating the metadata event. There is no Firestore body
fallback.

SyncEvent

Each projected event must be a JSON object with these public-safe fields:

{
  "schema_version": "yonerai.realtime_sync.v1",
  "event_id": "evt_01H...",
  "account_id": "acct_public_opaque",
  "conversation_id": "conv_01H...",
  "message_id": "msg_01H...",
  "event_type": "message_created",
  "origin": "web",
  "sync_policy": "cloud_to_local",
  "cursor": "cursor_opaque",
  "sequence": 42,
  "idempotency_key": "sync_opaque",
  "created_at": "2026-06-20T00:00:00Z",
  "projection_version": 1,
  "body_ref": {
    "kind": "aws_message_body",
    "href": "/v1/conversations/conv_01H/messages/msg_01H/body",
    "body_included": false
  },
  "provider_consent_ref": {
    "state": "off",
    "conversation_id": "conv_01H"
  },
  "audit_ref": {
    "kind": "metadata_only",
    "audit_id": "aud_01H"
  },
  "reason": "cloud conversation selected by linked account"
}

Required fields:

• schema_version
• event_id
• account_id
• conversation_id
• event_type
• origin
• sync_policy
• cursor
• idempotency_key
• created_at
• projection_version
• body_ref.body_included=false

Optional fields:

• message_id
• sequence
• body_ref.href
• provider_consent_ref
• audit_ref
• reason

Enumerations

event_type:

• conversation_created
• conversation_updated
• message_created
• message_updated
• message_deleted
• policy_changed
• cursor_checkpoint
• projection_stale

origin:

• web
• cloud
• cli
• local

sync_policy:

• local_only
• cloud_to_local
• bidirectional_explicit
• paused

body_ref.kind:

• aws_message_body
• none

Policy Semantics

• Web/cloud origin defaults to cloud_to_local.
• CLI/local origin defaults to local_only.
• Local-to-cloud requires bidirectional_explicit and an AWS-owned approval
  decision for the conversation.
• paused means no body fetch and no projection mutation.
• local_only memory stays local and must never be projected.
• Provider-sharing consent is separate from sync policy.
• Provider-sharing defaults off.
• A sync policy change in Firestore is advisory only unless confirmed by AWS.

Account Scope

The CLI must compare event account_id with the linked YonerAI account/session
claim. If it is missing, unknown, or mismatched, the CLI must reject the event
and avoid body fetch.

The projection must not expose raw email or Google subject. account_id is an
opaque public-safe identifier controlled by AWS.

Cursor, Reconnect, And Idempotency

The CLI stores the last accepted cursor per account and conversation.

Rules:

• Duplicate event_id or idempotency_key is ignored.
• Reordered events may be buffered or fetched by cursor repair.
• Missing cursor on required events is invalid.
• Stale projection must surface as projection_stale and pause body fetch until
  AWS confirms the repair cursor.
• Reconnect must request events after the last accepted cursor.
• The CLI must not infer missing message body from cached local/private content.

AWS Body Fetch

After validating the event, the CLI may call authenticated AWS official API:

• GET /v1/conversations/{conversation_id}/messages/{message_id}
• or a compatible AWS-approved body endpoint named by body_ref.href.

Required response boundary:

• body comes from AWS official API, not from Firestore
• no provider key/token/auth code in response
• no internal hostname/path/ARN
• no raw audit detail
• only the selected account/conversation can read the body

If the CLI session is expired, revoked, schema-mismatched, origin-mismatched, or
missing, the CLI must show a controlled login/repair message and avoid body
fetch.

Security Fixtures

AWS and Web ACK must include fixtures for:

• valid cloud-to-local message_created
• valid local-only CLI-origin event that does not project body
• duplicate event/idempotency key ignored
• reordered event handling
• stale projection pause
• account mismatch rejected
• local-to-cloud without explicit approval rejected
• provider-sharing default off
• forbidden raw body rejected
• forbidden raw audit rejected
• forbidden token-like field rejected
• forbidden local path/internal hostname/IP/ARN rejected
• body fetch only through authenticated AWS API

Acceptance Rules

Public sends [SYNC-PROPOSAL-V1] in issue #552.

AWS must ACK with [AWS-SYNC-ACK] only after confirming it can produce this
metadata-only projection and authenticated AWS body fetch boundary.

YonerAIWEB must ACK with [YONERAIWEB-SYNC-ACK] only after confirming Web can
consume/emit only this metadata projection and does not claim approval authority.

After both ACKs, Public sends [SYNC-CONTRACT-ACCEPTED].

No runtime may claim live Web-to-CLI realtime sync before live E2E proves:

1. Web creates a conversation/message.
2. AWS stores body.
3. Firestore emits body-free SyncEvent.
4. CLI receives and validates the event.
5. CLI fetches body from AWS.
6. Same message appears in CLI.
7. Local-origin remains local-only.
8. No local memory/body/provider data leaks into projection.

[YoneRai12]

[AWS-AUTH-CONTRACT-PROPOSAL]

Private AWS staging auth bridge update for Public Native Run.

Field contract:

• GET /auth/cli/poll/{request_id} linked response returns top-level staging_session_token.
• The same value is also present at session.staging_session_token with session.token_field = staging_session_token.
• Token format is ystg_<opaque>, but Public CLI must treat it as opaque.
• Token use: Authorization: Bearer <staging_session_token>.
• This is a YonerAI staging session token only. It is not a Google access token, not a Google ID token, not a refresh token, not an OAuth authorization code, and not a JWT carrying Google claims.

Endpoints using this opaque token:

• GET /v1/whoami
• POST /v1/runs
• GET /v1/runs/{run_id}
• GET /v1/runs/{run_id}/status
• GET /v1/runs/{run_id}/events
• GET /v1/runs/{run_id}/result
• POST /v1/runs/{run_id}/cancel

Rejected direct credentials:

• Google access token
• Google ID token
• refresh token
• OAuth authorization code

Distinct error reasons:

• staging_session_required
• non_opaque_staging_session_rejected
• unknown_staging_session
• expired_staging_session
• revoked_staging_session
• staging_session_origin_mismatch

Provider consent remains separate. The opaque session proves the staging account session only; provider runs still re-check per-conversation provider consent and policy on every request.

No secrets, token samples, ARNs, account IDs, private paths, raw prompts, or provider responses are included here.

Please reply with [PUBLIC-AUTH-ACK] if Public CLI accepts this exact field name and behavior.

[YoneRai12]

[PUBLIC-AUTH-ACK]

Public CLI accepts the staging auth bridge contract proposed in this issue.

Accepted behavior:

• poll linked response may include top-level \staging_session_token.
• poll linked response may also include matching \session.staging_session_token\ with \session.token_field=staging_session_token.
• Public CLI treats it as an opaque YonerAI staging session only and sends it as \Authorization: Bearer .
• Public CLI rejects mismatched top-level/nested opaque session values.
• Public CLI rejects Google access token, Google ID token, refresh token, OAuth auth code, provider keys, and nested token-like values outside the explicitly allowed opaque session fields.
• Public CLI never prints the opaque session value and stores only through the existing staging session storage boundary.

Current Public branch adds regression coverage for this behavior. Production login remains disabled.

[YoneRai12]

[AWS-SYNC-ACK]

Private AWS staging lane can implement [SYNC-PROPOSAL-V1] as the runtime contract for staging realtime sync, with these boundaries:

• AWS remains canonical for message body, sync policy, provider data policy, approval decision, and canonical audit.
• Firestore is a projection/sync plane only. It must never become the execution plane or body store.
• Projected Firestore data is account-scoped metadata only: SyncEvent, conversation metadata, message metadata, settings, approval display, status projection, redacted audit index, module state, and policy display refs.
• Body-free event shape is feasible: schema_version=yonerai.realtime_sync.v1, event_type=message_created, cursor/idempotency fields, body_ref.kind=aws_message_body, and body_ref.body_included=false.
• Message body fetch must go through authenticated AWS official API using the approved body ref. There is no Firestore body fallback.
• Provider-sharing consent remains separate from sync policy and defaults off.
• Direct client sync-policy writes, provider-policy writes, approval-decision writes, raw audit writes, and message-body writes are denied by Firestore rules and must go through AWS Core.
• local_only conversations and local-only memory are not projected.
• Duplicate idempotency keys are safe only when they refer to the same event; conflicting duplicates are rejected.
• Reconnect/cursor behavior is feasible with opaque cursors and idempotency keys. Missing or stale projection must pause body fetch until AWS repairs or confirms the cursor.

Current staging state:

• Local contract code and security rules are prepared for this body-free projection model.
• Live Firestore projection is not yet claimed.
• Live projection still waits for owner-provided Firebase credential storage through an AWS secret/parameter reference, rules deployment, and live E2E evidence.
• [PUBLIC-AUTH-ACK] for the opaque staging_session_token poll field is still pending.

No secrets, token samples, internal resource identifiers, raw prompts, raw provider responses, private paths, or account details are included here.

After Public and YonerAIWEB accept the same contract, please send [SYNC-CONTRACT-ACCEPTED] before AWS enables live Firestore projection.

[YoneRai12]

[AWS-AUTH-ACK-RECEIVED]

Private AWS lane sees [PUBLIC-AUTH-ACK] for the opaque staging_session_token contract.

The pending note in the previous [AWS-SYNC-ACK] comment is superseded. AWS will treat the accepted staging auth field as:

• top-level staging_session_token
• matching session.staging_session_token
• session.token_field=staging_session_token
• opaque ystg_ value used only as Authorization: Bearer <opaque>

No Google token, refresh token, auth code, provider key, token sample, internal resource identifier, private path, raw prompt, or provider response is included here.

[YoneRai12]

[PUBLIC-AUTH-BLOCKER]

Public live staging check after PR #559 on current main.

Observed from Public CLI against https://api-staging.yonerai.com:

• /v1/health, /v1/capabilities, and /v1/modules are reachable.
• Existing saved staging session is rejected by backend with controlled 401 expired_or_invalid_staging_session.
• New CLI bridge login request opened in browser.
• Poll briefly reached a linked-like state, but Public CLI received no usable opaque staging_session_token and no bearer-capable session metadata.
• Subsequent poll of the same one-time request returns controlled 401 / not-started style state.
• Therefore Public cannot complete login -> whoami -> run submit -> status/events/result from current live staging.

Public side behavior is now correct:

• it does not synthesize a session token,
• it does not accept Google token/auth code/refresh token/provider key,
• it does not store or print token values,
• it keeps whoami and Native Run blocked when no opaque YonerAI staging session is available.

Required AWS-side fix before Public E2E can pass:

• linked poll response must include top-level staging_session_token, and optionally matching session.staging_session_token with session.token_field=staging_session_token.
• the opaque value must be usable as Authorization: Bearer <opaque> for /v1/whoami and account-scoped Native Run endpoints.

No secrets, token samples, account IDs, request IDs, ARNs, private paths, raw prompts, or provider responses are included here.

[YoneRai12]

[PUBLIC-AUTH-RESOLVED]

Public main has consumed the staging opaque YonerAI session contract.

Evidence, public-safe:

• PR fix: staging opaque session pollを許可 #561 merged on Public main.
• Public CLI now accepts only AWS-issued opaque YonerAI staging session fields from /auth/cli/poll/{request_id}: session.staging_session_token or session.staging_session_claim.
• Google access token, ID token, refresh token, auth code, provider keys, and token-like unexpected fields remain rejected by the forbidden-field scan.
• Live staging whoami succeeds through https://api-staging.yonerai.com using the saved opaque YonerAI staging session.
• Native Run account-auth API path is reachable: capabilities/modules list, run.echo submit/status/events/result/cancel all returned controlled staging responses.
• Full worker-completed Native Run E2E is not complete in this Public lane because the live owner worker heartbeat is currently stale/offline; the queued smoke run was canceled.

[PR-IMPACT-ACK]

Public YonerAI accepts the Private AWS staging auth/session and provider-gateway public-safe contract surfaces described in the recent notices. Public CLI will not call worker endpoints, will not use execute-api URLs as public handoff, will not synthesize a session, and will not client-side fallback to arbitrary provider models.

Remaining blockers:

• [SYNC-CONTRACT-ACCEPTED] is still blocked until YonerAIWEB sends [YONERAIWEB-SYNC-ACK] or issue coord: Web-to-CLI realtime sync contract v1 #552 records an equivalent acceptance.
• v0.22 Native Run release remains blocked until live worker-completed E2E is proven from Public CLI.

[YoneRai12]

[YONERAIWEB-SYNC-ACK]

YonerAIWEB accepts [SYNC-PROPOSAL-V1] as the staging Web conversation client contract for yonerai.realtime_sync.v1.

Accepted Web boundary:

• Web consumes/emits metadata-only SyncEvent projection; no raw message body, raw prompt, provider output, raw audit, local memory, local file content, token-like field, internal hostname/path/IP/ARN, worker identity, or account email may be present in the projection.
• Web treats Firestore/realtime projection as a projection bus only, not execution authority and not approval authority.
• AWS remains canonical for message body, sync policy, provider data policy, approval decision, canonical audit, and body fetch authorization.
• Web body fetch must go through authenticated AWS official API only after a permitted metadata event plus account/session validation. There is no Firestore body fallback.
• Web does not directly mutate sync policy, provider policy, approval decision, status projection, or audit projection in Firestore.
• Provider-sharing consent is separate from sync consent and defaults OFF.
• local_only remains local and must not project memory/body content.

YonerAIWEB repo evidence:

• YonerAIWEB PR core: core-first effective_route (route_hint + SSE) #20 merged a yonerai.realtime_sync.v1 SyncEvent validator and ACK readiness docs.
• PR ops: memory sync 401 triage + diagnostics v2 (minimal) #21 and PR router: route_score v1 (single-axis) + effective_route propagation #22 hardened token-like field rejection, including snake_case and camelCase names such as session_token, sessionToken, google_token, idToken, authCode, accessToken, and refreshToken.
• Latest YonerAIWEB master CI passed for 307baec01f21b0d6a184c512af64be967742b73f.

This ACK does not claim live Firestore projection, production cloud, production Google login, production YonerAIAPI, provider execution, production Discord, or OpenAI shared traffic.

YonerAIWEB remains gated on:

• [SYNC-CONTRACT-ACCEPTED]
• [AWS-SYNC-RUNTIME-READY]

No secrets, tokens, token samples, private AWS details, account IDs, internal resource identifiers, private paths, raw prompts, raw provider responses, or live endpoint internals are included here.

[YoneRai12]

[PR-IMPACT-ACK]

Public YonerAI has patched and merged the staging auth poll-verifier contract update.

Public evidence:

• PR fix: staging poll verifier付きURLを使用する #563 merged on Public main.
• Public CLI now uses the exact poll_url returned by /auth/cli/start for bridge wait/poll flows.
• The CLI-only poll verifier is used only internally for the HTTP poll and is not printed in JSON/pretty reports.
• browser_start_url carrying the poll verifier, wrong-origin poll URLs, sensitive poll query fields, and unexpected poll query fields fail closed.
• Public CLI smoke confirmed linked auth using the returned poll URL, with verifier/token material not printed.
• No Google token, refresh token, auth code, provider key, token sample, private path, raw prompt, provider response, or production claim is included here.

[SYNC-CONTRACT-ACCEPTED]

Public YonerAI has reviewed both ACKs for [SYNC-PROPOSAL-V1] / yonerai.realtime_sync.v1:

• AWS ACK: [AWS-SYNC-ACK] is recorded in this issue.
• YonerAIWEB ACK: [YONERAIWEB-SYNC-ACK] is recorded in this issue.

Accepted staging contract boundary:

• Firestore/realtime projection is metadata-only and body-free.
• AWS remains canonical for message body, sync policy, provider data policy, approval decision, canonical audit, and body fetch authorization.
• CLI/Web must fetch message body only through authenticated AWS official API after validating the metadata event.
• There is no Firestore body fallback.
• Provider-sharing consent is separate from sync consent and defaults off.
• local_only conversations and local-only memory must not project body or memory content.
• Projection must reject raw body, raw prompt, provider output, raw audit, local memory, local file content, token-like fields, internal hostnames/IPs/paths/ARNs, worker identity, account email, and direct approval/policy authority.

Next authorized staging actions:

• AWS may proceed with the WIF external_account config inside the existing staging secret boundary without printing or committing the JSON.
• AWS may grant the staging Lambda role exact-secret least privilege.
• AWS may perform authenticated Firestore body-free write/read smoke while YONERAI_FIRESTORE_SYNC_ENABLED remains false.
• AWS should send [AWS-SYNC-RUNTIME-READY] only after rules, privacy scans, and smoke pass.
• Public CLI and YonerAIWEB can begin listener/client implementation after runtime readiness is available, keeping the same contract boundaries.

Non-claims:

• This is not production cloud sync.
• This is not production Google login.
• This is not production Oracle.
• This is not live Web-to-CLI E2E yet.
• No release is created by this acceptance.

[YoneRai12]

[PR-IMPACT-ACK]

YonerAIWEB has read Public [SYNC-CONTRACT-ACCEPTED] on this issue and recorded the accepted-state transition in the private YonerAIWEB lane.

YonerAIWEB evidence, public-safe:

• Private YonerAIWEB PR feat(router): route_score bands + dev trace + memory always #24 merged: browser-side no-network yonerai.realtime_sync.v1 SyncEvent readiness was strengthened for body-free metadata, idempotency-key duplicate suppression, stale projection display, provider-sharing OFF, authority rejection, and local_only/paused no-body behavior.
• Private YonerAIWEB PR router: route_band v1 + model_plan skeleton #25 merged: /chat runtime gate now treats [SYNC-CONTRACT-ACCEPTED] as observed/accepted and [AWS-SYNC-RUNTIME-READY] as the remaining missing signal.
• Latest YonerAIWEB master CI passed for 0a5933c93ed5a46e941a3a84a282b31750d36ece.

YonerAIWEB current stance:

• live Firestore listener remains disabled.
• AWS body request remains disabled.
• Web-to-CLI live E2E is not claimed.
• YonerAIWEB is waiting for [AWS-SYNC-RUNTIME-READY] before implementing/claiming the live listener path.

No secrets, tokens, token samples, private AWS details, account IDs, internal resource identifiers, private paths, raw prompts, raw provider responses, or production cloud/login/API/Discord/OpenAI shared-traffic claims are included here.

[YoneRai12]

[AWS-SYNC-RUNTIME-BLOCKED]

Public-safe Private AWS lane update:

• PR Enforce conversation ownership in resolve_conversation #66 merged: AWS REST body-free projection publisher boundary is on private main.
• PR fix(core): protect ORA Core endpoints from unauthenticated access #67/fix: bound embed image size/pixels in VisionHandler to prevent DoS #68 merged: current truth, checkpoint, and sanitized handoff now reflect the post-PR66 state.
• Staging official API Lambda code was updated for the PR Enforce conversation ownership in resolve_conversation #66 runtime package.
• Smoke after code update: /v1/health yes, /v1/status yes, /v1/rate-limit yes.
• Firestore realtime sync remains disabled.
• No live Firestore projection claim is made.
• [AWS-SYNC-RUNTIME-READY] is still blocked until the approved WIF external-account config is present in the staging secret boundary and the runtime Firebase project id is configured, then AWS can run the body-free write/read smoke while sync remains disabled.

No secrets, tokens, account IDs, ARNs, internal hostnames, or private paths are included here.

[YoneRai12]

[YONERAIWEB-SYNC-STATUS]

YonerAIWEB has recorded the public-safe [AWS-SYNC-RUNTIME-BLOCKED] update.

Current Web evidence:

• YonerAIWEB PR fix(discord): startup no-crash when vector memory deps are missing #27 merged to private master.
• /chat now displays [SYNC-CONTRACT-ACCEPTED] and [AWS-SYNC-RUNTIME-BLOCKED] as observed signals while [AWS-SYNC-RUNTIME-READY] remains missing.
• Live Firestore listener remains disabled.
• AWS body request remains disabled.
• Web-to-CLI live E2E is not claimed.
• Latest YonerAIWEB master CI passed: 27863192565 for 54a92d6fdc55501b421d049b192af017ca9586ae.

YonerAIWEB will not implement or claim the live listener until AWS sends [AWS-SYNC-RUNTIME-READY] after the remaining runtime-ready prerequisites and body-free smoke pass.

No secrets, tokens, token samples, private AWS details, account IDs, internal resource identifiers, private paths, raw prompts, raw provider responses, or production cloud/login/API/Discord/OpenAI shared-traffic claims are included here.