@yalehwang/cloudpit 2.0.0 → 3.0.0

package/server/modules/oauth/tests/oauth-consent-page.test.ts

@@ -21,14 +21,14 @@
  *       contains HTML — plus the correct callback host (AC4). [was the AC-260 (a)
  *       HTML-escaping leg: the server renders no HTML any more, so escaping has no
  *       subject; the honest translation is that the value is structured data.]
- *   (c) GET context returns the whole scope vocabulary, `cloudcli:read` flagged
+ *   (c) GET context returns the whole scope vocabulary, `cloudpit:read` flagged
  *       `required:true`/`writable:false`, the rest `required:false`/`writable:true`,
  *       and never `cloudcli:admin` (AC4; old (b)/(m)'s intent).
  *   (d) decision deny → `redirectTo` carries `error=access_denied` and the verbatim
  *       state, no code, no new code row (AC6; old (d)).
  *   (e) decision allow → `redirectTo` carries a non-empty code and the verbatim
  *       state, and the grant row's scopes are exactly the submitted set ∪
- *       `cloudcli:read`, once each (AC5; old (c)/(e)).
+ *       the canonical `cloudcli:read`, once each (AC5; old (c)/(e)).
  *   (f) an unregistered `redirect_uri` is refused at GET /oauth/authorize (400
  *       error page, NO Location), at context (400 JSON) and at decision for BOTH
  *       allow and deny (400, no `redirectTo`, no code row) — the deny branch is
@@ -107,6 +107,9 @@ import { OAUTH_CONSENT_SPA_PATH } from '../../../../shared/oauthConsent.js';
 const PUBLIC_BASE_URL = 'https://cli.example';
 const REDIRECT_URI = 'https://app.example/cb';
 const START_MS = Date.UTC(2026, 0, 1, 0, 0, 0);
+// 3.0 splits the two vocabularies: the consent screen OFFERS the wire spelling
+// (`cloudpit:*`), while a granted decision is STORED under the canonical name
+// (`cloudcli:*`) so the existing `requiredScopes` literals keep matching.
 const READ_SCOPE = 'cloudcli:read';
 const WRITE_SCOPE = 'cloudcli:session:send';
 const CREATE_SCOPE = 'cloudcli:session:create';
@@ -114,12 +117,14 @@ const CONTROL_SCOPE = 'cloudcli:session:control';
 const NAVIGATE_SCOPE = 'cloudcli:navigate';
 const APPROVE_SCOPE = 'cloudcli:approve';
 // gap-ui-visible-context-extended-fields: the appended content scope, offered by
-// the consent screen since it maps the whole ACCESS_TOKEN_SCOPES vocabulary.
+// the consent screen since it maps the whole wire vocabulary.
 const SELECTION_SCOPE = 'cloudcli:selection';
 // gap-mcp-cockpit-card-tools: the appended confirm scope. It is a WRITE scope —
 // confirming a card runs the option's declared executor — so leg (c) requires it
 // to carry a `write` group and a non-empty risk badge, which it does.
 const COCKPIT_ACT_SCOPE = 'cloudcli:cockpit:act';
+
+/** The wire spelling of each canonical constant: what the consent screen offers and accepts. */
 const VOCABULARY = [
   READ_SCOPE,
   WRITE_SCOPE,
@@ -129,6 +134,9 @@ const VOCABULARY = [
   NAVIGATE_SCOPE,
   SELECTION_SCOPE,
   COCKPIT_ACT_SCOPE,
+].map((scope) => scope.replace('cloudcli:', 'cloudpit:'));
+const [READ_WIRE, WRITE_WIRE, CREATE_WIRE, , , NAVIGATE_WIRE] = VOCABULARY as [
+  string, string, string, string, string, string, string, string,
 ];
 const USER_ID = 1;
 const OWNER = 'owner';
@@ -271,7 +279,7 @@ function latestGrantScopes(): string[] {
 function authorizeQuery(
   clientId: string,
   challenge: string,
-  scopes: string[] = [READ_SCOPE],
+  scopes: string[] = [READ_WIRE],
   state = 'xyz',
   redirectUri: string = REDIRECT_URI
 ): string {
@@ -336,7 +344,7 @@ test('(a) GET /oauth/authorize 302s to the relative SPA route, query preserved i
   await withConsentServer(async (harness) => {
     const clientId = harness.registerClient('consent-app');
     const pair = pkcePair();
-    const query = authorizeQuery(clientId, pair.challenge, [READ_SCOPE, WRITE_SCOPE], 'state-abc');
+    const query = authorizeQuery(clientId, pair.challenge, [READ_WIRE, WRITE_WIRE], 'state-abc');
     const response = await fetch(`${harness.baseUrl}/oauth/authorize?${query}`, { redirect: 'manual' });
     assert.equal(response.status, 302);
     const location = response.headers.get('location') ?? '';
@@ -368,7 +376,7 @@ test('(b) GET context returns the client name as JSON data (verbatim) and the ri
   });
 });
 
-test('(c) GET context returns the whole vocabulary with cloudcli:read required and non-writable', async () => {
+test('(c) GET context returns the whole wire vocabulary with cloudpit:read required and non-writable', async () => {
   await withConsentServer(async (harness) => {
     const clientId = harness.registerClient('consent-app');
     const reading = await getContext(harness, clientId);
@@ -377,7 +385,7 @@ test('(c) GET context returns the whole vocabulary with cloudcli:read required a
     assert.deepEqual(scopes.map((entry) => entry.scope), VOCABULARY, 'the whole vocabulary, in order');
     for (const entry of scopes) {
       assert.ok(entry.description.length > 0, `${entry.scope} must carry an English description`);
-      if (entry.scope === READ_SCOPE) {
+      if (entry.scope === READ_WIRE) {
         assert.equal(entry.required, true, 'the read-only scope is pinned');
         assert.equal(entry.writable, false, 'the read-only scope is not removable');
       } else {
@@ -391,7 +399,7 @@ test('(c) GET context returns the whole vocabulary with cloudcli:read required a
     // and, for a state-changing scope, a risk code the badge renders from. The
     // existing assertions above are untouched; these are additive.
     for (const entry of scopes) {
-      if (entry.scope === READ_SCOPE) {
+      if (entry.scope === READ_WIRE) {
         assert.equal(entry.group, 'read', 'the pinned scope is filed under the read group');
         assert.equal(entry.risk, null, 'a read scope carries no risk badge');
       } else {
@@ -416,7 +424,7 @@ test('(d) decision deny returns error=access_denied with the verbatim state and
       state: 'state-deny-1',
       code_challenge: pkcePair().challenge,
       code_challenge_method: 'S256',
-      scopes: [READ_SCOPE],
+      scopes: [READ_WIRE],
       action: 'deny',
     });
     assert.equal(denied.status, 200);
@@ -430,7 +438,7 @@ test('(d) decision deny returns error=access_denied with the verbatim state and
   });
 });
 
-test('(e) decision allow returns a code and stores the submitted set plus cloudcli:read', async () => {
+test('(e) decision allow returns a code and stores the canonical set plus the read scope', async () => {
   await withConsentServer(async (harness) => {
     const clientId = harness.registerClient('consent-app');
     const pair = pkcePair();
@@ -443,7 +451,7 @@ test('(e) decision allow returns a code and stores the submitted set plus cloudc
       code_challenge_method: 'S256',
       // The read-only box is pinned on the client, so it is not submitted; the
       // control scope was left unchecked.
-      scopes: [WRITE_SCOPE],
+      scopes: [WRITE_WIRE],
       action: 'allow',
     });
     assert.equal(allowed.status, 200);
@@ -469,7 +477,7 @@ test('(f) an unregistered redirect_uri is refused at authorize, context and deci
 
     // GET /oauth/authorize: an error page and NO Location header.
     const getResponse = await fetch(
-      `${harness.baseUrl}/oauth/authorize?${authorizeQuery(clientId, pkcePair().challenge, [READ_SCOPE], 'xyz', evil)}`,
+      `${harness.baseUrl}/oauth/authorize?${authorizeQuery(clientId, pkcePair().challenge, [READ_WIRE], 'xyz', evil)}`,
       { redirect: 'manual' }
     );
     const getBody = await getResponse.text();
@@ -492,7 +500,7 @@ test('(f) an unregistered redirect_uri is refused at authorize, context and deci
         state: 'xyz',
         code_challenge: pkcePair().challenge,
         code_challenge_method: 'S256',
-        scopes: [READ_SCOPE],
+        scopes: [READ_WIRE],
         action,
       });
       assert.equal(response.status, 400, `decision ${action} to an unregistered callback must be refused`);
@@ -518,7 +526,7 @@ test('(g) the JSON API carries the anti-framing and no-store headers', async ()
       state: 'xyz',
       code_challenge: pkcePair().challenge,
       code_challenge_method: 'S256',
-      scopes: [READ_SCOPE],
+      scopes: [READ_WIRE],
       action: 'deny',
     });
     assert.equal(decision.headers.get('x-frame-options'), 'DENY');
@@ -542,7 +550,7 @@ test('(g) the JSON API carries the anti-framing and no-store headers', async ()
 test('(h) the SPA document at /oauth/consent carries the three headers over the static layer', async () => {
   await withConsentServer(async (harness) => {
     const clientId = harness.registerClient('consent-app');
-    const query = authorizeQuery(clientId, pkcePair().challenge, [READ_SCOPE], 'state-doc');
+    const query = authorizeQuery(clientId, pkcePair().challenge, [READ_WIRE], 'state-doc');
     const response = await fetch(`${harness.baseUrl}${OAUTH_CONSENT_SPA_PATH}?${query}`);
     assert.equal(response.status, 200, 'the SPA document is served from dist/index.html');
     assert.match(response.headers.get('content-type') ?? '', /text\/html/);
@@ -616,7 +624,7 @@ test('(k) context and decision without a JWT are 401 and create no code row', as
         state: 'xyz',
         code_challenge: pkcePair().challenge,
         code_challenge_method: 'S256',
-        scopes: [READ_SCOPE],
+        scopes: [READ_WIRE],
         action: 'allow',
       },
       null
@@ -637,7 +645,7 @@ test('(m) a forged scope outside the vocabulary never reaches the grant', async
       state: 'xyz',
       code_challenge: pkcePair().challenge,
       code_challenge_method: 'S256',
-      scopes: ['cloudcli:admin', 'bogus', CREATE_SCOPE, CREATE_SCOPE, NAVIGATE_SCOPE],
+      scopes: ['cloudcli:admin', 'bogus', CREATE_WIRE, CREATE_WIRE, NAVIGATE_WIRE],
       action: 'allow',
     });
     assert.equal(allowed.status, 200);
@@ -696,7 +704,7 @@ test('(o) a read-only allow with no password and no injected verifier mints a co
       state: 'state-readonly',
       code_challenge: pkcePair().challenge,
       code_challenge_method: 'S256',
-      scopes: [READ_SCOPE],
+      scopes: [READ_WIRE],
       action: 'allow',
       password: '',
     });
@@ -720,7 +728,7 @@ test('(p) a deny carrying a write scope and no password is still access_denied',
       state: 'state-deny-write',
       code_challenge: pkcePair().challenge,
       code_challenge_method: 'S256',
-      scopes: [WRITE_SCOPE],
+      scopes: [WRITE_WIRE],
       action: 'deny',
       password: '',
     });
@@ -773,7 +781,7 @@ test('(l) in a real browser the 302 lands on the SPA route and the window.locati
       body: JSON.stringify({
         client_id: q.get('client_id'), redirect_uri: q.get('redirect_uri'), state: q.get('state'),
         code_challenge: q.get('code_challenge'), code_challenge_method: 'S256',
-        scopes: ['cloudcli:read'], action: 'allow',
+        scopes: ['cloudpit:read'], action: 'allow',
       }),
     }).then((r) => r.json());
     window.location.href = decision.redirectTo;
@@ -802,7 +810,7 @@ test('(l) in a real browser the 302 lands on the SPA route and the window.locati
       const callback = `${callbackOrigin}/cb`;
       const clientId = harness.registerClient('browser-app', callback);
       const pair = pkcePair();
-      const query = authorizeQuery(clientId, pair.challenge, [READ_SCOPE], 'state-browser', callback);
+      const query = authorizeQuery(clientId, pair.challenge, [READ_WIRE], 'state-browser', callback);
 
       const page = await browser.newPage();
       await page.goto(`${harness.baseUrl}/oauth/authorize?${query}`);

package/server/modules/oauth/tests/oauth-consent-ratelimit.test.ts

@@ -65,13 +65,13 @@ import type { OAuthProvider } from '@/modules/oauth/index.js';
 
 const CLIENT_ID = 'client-ratelimit';
 const REDIRECT_URI = 'https://app.example/cb';
-const READ_SCOPE = 'cloudcli:read';
+const READ_SCOPE = 'cloudpit:read';
 /**
  * A state-changing scope. The password branch is now reached ONLY by a grant that
  * goes past `cloudcli:read`, so the legs that are about the password (a–h below)
  * must submit this rather than the read scope.
  */
-const WRITE_SCOPE = 'cloudcli:session:send';
+const WRITE_SCOPE = 'cloudpit:session:send';
 /** Fifteen minutes, the AC's window; also the amount leg (b) advances past. */
 const WINDOW_MS = 15 * 60 * 1000;
 const MAX_ATTEMPTS = 10;

package/server/modules/oauth/tests/token-info.routes.test.ts

@@ -89,7 +89,7 @@ function issueToken(harness: Harness, expiresInDays: number): IssuedToken {
   const issued = harness.tokens.issueToken({
     userId: USER_ONE,
     name: 'self-check',
-    scopes: ['cloudcli:read'],
+    scopes: ['cloudpit:read'],
     expiresInDays,
   });
   if (!issued.ok) {
@@ -111,7 +111,7 @@ test('(a) a live token answers 200 with its owner, scopes and expiry, verified p
     assert.equal(response.status, 200);
     const body = await response.json() as { userId: number; scopes: string[]; expiresAt: string };
     assert.equal(body.userId, USER_ONE);
-    assert.deepEqual(body.scopes, ['cloudcli:read']);
+    assert.deepEqual(body.scopes, ['cloudpit:read'], 'the token row keeps the issued wire spelling');
     assert.equal(body.expiresAt, token.expiresAt);
 
     // No cache: the row is read on every request, so a second call answers the

package/server/modules/observation/architecture-delta.producer.ts

@@ -42,7 +42,7 @@ export const ARCHITECTURE_DELTA_REFRESH_MS = 60 * 60 * 1000;
 /**
  * The project the producer observes.
  *
- * `projectId` addresses the CloudCLI project the architecture service resolves to a root;
+ * `projectId` addresses the Cloudpit project the architecture service resolves to a root;
  * `fleetProjectId` is what the `cloudcli://architecture/<id>` URI (and therefore the wall) uses.
  * A project without a fleet id has no addressable tile and is skipped — the same rule the
  * project-truth producer applies to its unregistered projects.

package/server/modules/observation/blind-spots.ts

@@ -40,7 +40,7 @@ const SESSION_LLM_BLIND_SPOTS: readonly string[] = [
 /** What the layered project-truth reading cannot see. */
 const PROJECT_BLIND_SPOTS: readonly string[] = [
   '看不见未登记到 quay-fleet 的项目与不经 quay 的工作',
-  '部署层只对 CloudCLI 自身有意义',
+  '部署层只对 Cloudpit 自身有意义',
   '验证层只反映 gate 的判据，不反映判据本身是否判别',
 ];
 

package/server/modules/observation/observation-store.ts

@@ -38,8 +38,10 @@ import {
   withBlindSpotsInDigest,
 } from './blind-spots.js';
 import {
+  canonicalObservationUri,
   parseObservationUri,
   type ObservationKind,
+  type ObservationUri,
 } from './observation-uri.js';
 import { evaluateProducer, type ProducerReading } from './producer-liveness.js';
 
@@ -250,7 +252,9 @@ function toObservedObject(row: ObservedObjectRow): ObservedObject {
     tier,
   );
   return {
-    uri: row.uri,
+    // Stored rows are canonical `cloudpit://` keys (the 2.1 normalization moved the 2.0 rows);
+    // the projection normalizes once more so every reading of an object is one string.
+    uri: canonicalObservationUri(row.uri),
     kind,
     title: row.title,
     status,
@@ -267,12 +271,17 @@ function toObservedObject(row: ObservedObjectRow): ObservedObject {
 }
 
 function toSeenCursor(row: ObservationSeenCursorRow): SeenCursor {
-  return { userId: row.userId, uri: row.uri, revision: row.revision, at: row.at };
+  return {
+    userId: row.userId,
+    uri: canonicalObservationUri(row.uri),
+    revision: row.revision,
+    at: row.at,
+  };
 }
 
 function toObservedRevision(row: ObservedRevisionRow): ObservedRevision {
   return {
-    uri: row.uri,
+    uri: canonicalObservationUri(row.uri),
     revision: row.revision,
     at: row.at,
     deltaItems: parseDeltaItems(row.deltaItemsJson),
@@ -311,8 +320,22 @@ export function createObservationStore(deps: ObservationStoreDeps = {}): Observa
   }
   const publish = deps.publish ?? (() => {});
 
+  /**
+   * The row key a write must use. 3.0 has exactly one spelling: a new object lands on (and an
+   * existing object continues) the canonical `cloudpit://` key. The 2.1 key normalization already
+   * moved the rows a 2.0 producer wrote, so no read has to try a legacy key any more.
+   */
+  const storageUriOf = (parsed: ObservationUri): string => parsed.uri;
+
+  /** Revisions for the one canonical spelling, oldest first. */
+  const revisionsAfter = (uri: string, afterRevision: number): ObservedRevisionRow[] => {
+    return observationDb.listRevisionsAfter(uri, afterRevision);
+  };
+
   const publishRevision = (uri: string, revision: number, status: ObservedStatus, deltaItems: string[]): void => {
-    const recipients = new Set([...observationDb.listWatchUserIds(uri), ...observationDb.listSeenUserIds(uri)]);
+    const recipients = new Set<string>();
+    for (const userId of observationDb.listWatchUserIds(uri)) recipients.add(userId);
+    for (const userId of observationDb.listSeenUserIds(uri)) recipients.add(userId);
     for (const userId of recipients) {
       publish(userId, { kind: 'observation.update', uri, revision, seenRevision: null, deltaItems });
     }
@@ -321,7 +344,7 @@ export function createObservationStore(deps: ObservationStoreDeps = {}): Observa
   const requireUri = (value: unknown) => {
     const parsed = parseObservationUri(value);
     if (parsed === null) {
-      throw invalid('`uri` must be one of cloudcli://session/<id> (or cloudpit://session/<id>), cloudcli://architecture/<id> (or cloudpit://architecture/<id>), quay://<id>/board', 'INVALID_URI');
+      throw invalid('`uri` must be one of cloudpit://session/<id>, cloudpit://architecture/<id>, quay://<id>/board', 'INVALID_URI');
     }
     return parsed;
   };
@@ -367,7 +390,7 @@ export function createObservationStore(deps: ObservationStoreDeps = {}): Observa
       const items = deltaItems.map((item) => item.trim()).filter((item) => item !== '');
 
       const appended = observationDb.appendRevision({
-        uri: parsed.uri,
+        uri: storageUriOf(parsed),
         kind,
         title,
         statusState: status.state,
@@ -405,7 +428,7 @@ export function createObservationStore(deps: ObservationStoreDeps = {}): Observa
       if (!Number.isInteger(afterRevision) || afterRevision < 0) {
         throw invalid('`revision` must be a non-negative integer');
       }
-      return observationDb.listRevisionsAfter(parsed.uri, afterRevision).map(toObservedRevision);
+      return revisionsAfter(parsed.uri, afterRevision).map(toObservedRevision);
     },
 
     markSeen(userId, uri, revision) {
@@ -421,6 +444,7 @@ export function createObservationStore(deps: ObservationStoreDeps = {}): Observa
         return { cursor: toSeenCursor(current), advanced: false };
       }
       const at = now();
+      // One spelling, one row: the cursor always lives under the canonical address.
       observationDb.writeSeenCursor(key, parsed.uri, revision, at);
       const cursor: SeenCursor = { userId: key, uri: parsed.uri, revision, at };
       const object = readObject(parsed.uri);
@@ -446,8 +470,8 @@ export function createObservationStore(deps: ObservationStoreDeps = {}): Observa
       const key = userKey(userId);
       const parsed = requireUri(uri);
       const at = now();
-      const row = observationDb.writeWatchEntry(key, parsed.uri, at);
-      const entry: WatchEntry = { userId: row.userId, uri: row.uri, pinnedAt: row.pinnedAt };
+      const row = observationDb.writeWatchEntry(key, storageUriOf(parsed), at);
+      const entry: WatchEntry = { userId: row.userId, uri: parsed.uri, pinnedAt: row.pinnedAt };
       publish(key, {
         kind: 'observation.update',
         uri: parsed.uri,
@@ -474,16 +498,30 @@ export function createObservationStore(deps: ObservationStoreDeps = {}): Observa
 
     getWall(userId) {
       const key = userKey(userId);
-      const pins = observationDb.listWatchEntries(key);
-      const pinnedUris = new Set(pins.map((pin) => pin.uri));
+      // Pins and cursors are already canonical; normalization keeps the join key one string.
+      const pinnedUris = new Set(
+        observationDb.listWatchEntries(key).map((pin) => canonicalObservationUri(pin.uri)),
+      );
       const cursors = new Map<string, number>();
       for (const cursor of observationDb.listSeenCursors(key)) {
-        cursors.set(cursor.uri, cursor.revision);
+        const uri = canonicalObservationUri(cursor.uri);
+        cursors.set(uri, Math.max(cursors.get(uri) ?? 0, cursor.revision));
       }
 
-      const candidates: ObservationWallEntry[] = [];
+      // One wall entry per canonical address even if both spellings have a row: the higher
+      // revision is the object's current state (a 2.0 row plus a post-flip row never doubles it).
+      const objects = new Map<string, ObservedObject>();
       for (const row of observationDb.listObjects()) {
+        // 3.0 reads one spelling: a pre-normalization row still keyed `cloudcli://` is not an
+        // address this release can show (the 2.1 migration moved the rows it could reach).
+        if (parseObservationUri(row.uri) === null) continue;
         const object = toObservedObject(row);
+        const known = objects.get(object.uri);
+        if (known === undefined || object.revision > known.revision) objects.set(object.uri, object);
+      }
+
+      const candidates: ObservationWallEntry[] = [];
+      for (const object of objects.values()) {
         const pinned = pinnedUris.has(object.uri);
         // An unpinned object is on the wall only while it needs attention; recovering to `ok`
         // (or to any other non-attention reading) is what makes it leave again.
@@ -491,9 +529,9 @@ export function createObservationStore(deps: ObservationStoreDeps = {}): Observa
           continue;
         }
         const seenRevision = cursors.get(object.uri) ?? 0;
-        const deltaItems = observationDb
-          .listRevisionsAfter(object.uri, seenRevision)
-          .flatMap((revision) => parseDeltaItems(revision.deltaItemsJson));
+        const deltaItems = revisionsAfter(object.uri, seenRevision).flatMap((revision) =>
+          parseDeltaItems(revision.deltaItemsJson),
+        );
         candidates.push({ object, pinned, seenRevision, deltaItems });
       }
 

package/server/modules/observation/observation-uri.ts

@@ -7,22 +7,27 @@
  * let a typo create a second object for the same conversation, which is exactly the
  * "unobservable-because-misaddressed" failure this layer exists to prevent.
  *
- *   cloudcli://session/<id>              — one CloudCLI session
- *   cloudcli://architecture/<projectId>  — one project's architecture graph
+ *   cloudpit://session/<id>              — one Cloudpi session (canonical since 2.1)
+ *   cloudpit://architecture/<projectId>  — one project's architecture graph
  *   quay://<fleetProjectId>/board        — one fleet project's board (the fleet's own grammar)
  *   quay://fleet/initiative/<slug>       — one cross-project initiative (the fleet's reserved segment)
  *
+ * 3.0 OWNS ONE SPELLING. 2.1 switched the write and kept the legacy `cloudcli://session/<id>` /
+ * `cloudcli://architecture/<id>` read spellings; this release retires those reads, so the parser
+ * accepts only the canonical `cloudpit://` forms. The 2.1 key normalization already moved stored
+ * object rows onto that spelling. See `docs/proposals/cloudpit-compat-retirement.md` (R6/R7).
+ *
  * The initiative address is the fleet's (`ADR-013` reserves `fleet` for exactly this object).
  * The cockpit's initiative view pins it to the wall, so the watch routes must accept it even
  * though no observation producer writes an object ROW for it: a pin is a user's bookmark, and
  * refusing the fleet's own address would make 「钉到观察墙」 impossible for the object the
  * initiative view is about.
  *
- * The cloudcli scheme is CloudCLI's; quay's board URI is kept verbatim because the fleet owns
- * that address space and will own its "seen" write-back later (see the task's Notes). An id
- * segment may not be empty, may not contain `/`, `?`, `#` or whitespace, and is not
- * percent-decoded here: the routes decode the path parameter once, and every other caller
- * builds the URI with the formatters below.
+ * The cloud scheme is Cloudpi's; quay's board URI is kept verbatim because the fleet owns that
+ * address space and will own its "seen" write-back later (see the task's Notes). An id segment
+ * may not be empty, may not contain `/`, `?`, `#` or whitespace, and is not percent-decoded
+ * here: the routes decode the path parameter once, and every other caller builds the URI with
+ * the formatters below.
  *
  * Consumers: `server/modules/observation/observation-store.ts` (write validation and the wall)
  * and `server/modules/observation/observation.routes.ts` (transport validation).
@@ -38,27 +43,27 @@ export type ObservationKind = 'session' | 'project' | 'architecture';
  * caller can use the parsed value as a map key without re-formatting it.
  */
 export type ObservationUri =
-  | { scheme: 'cloudcli'; kind: 'session'; id: string; uri: string }
-  | { scheme: 'cloudcli'; kind: 'architecture'; id: string; uri: string }
+  | { scheme: 'cloudpit'; kind: 'session'; id: string; uri: string }
+  | { scheme: 'cloudpit'; kind: 'architecture'; id: string; uri: string }
   | { scheme: 'quay'; kind: 'project'; id: string; uri: string }
   | { scheme: 'quay'; kind: 'initiative'; id: string; uri: string };
 
 /** One path segment: at least one character, none of the URI's structural characters. */
 const SEGMENT = '[^/?#\\s]+';
 
-const CLOUDCLI_URI = new RegExp(`^(?:cloudcli|cloudpit)://(session|architecture)/(${SEGMENT})$`);
+const CLOUDPIT_URI = new RegExp(`^cloudpit://(session|architecture)/(${SEGMENT})$`);
 const QUAY_BOARD_URI = new RegExp(`^quay://(${SEGMENT})/board$`);
 /** The fleet's one reserved address: `fleet` is not a project, and only `initiative` lives there. */
 const QUAY_INITIATIVE_URI = new RegExp(`^quay://fleet/initiative/(${SEGMENT})$`);
 
-/** The canonical `cloudcli://session/<id>` spelling. */
+/** The canonical `cloudpit://session/<id>` spelling 2.1 writes. */
 export function formatSessionUri(id: string): string {
-  return `cloudcli://session/${id}`;
+  return `cloudpit://session/${id}`;
 }
 
-/** The canonical `cloudcli://architecture/<id>` spelling. */
+/** The canonical `cloudpit://architecture/<id>` spelling 2.1 writes. */
 export function formatArchitectureUri(projectId: string): string {
-  return `cloudcli://architecture/${projectId}`;
+  return `cloudpit://architecture/${projectId}`;
 }
 
 /** The canonical `quay://<fleetProjectId>/board` spelling. */
@@ -94,13 +99,11 @@ export function formatObservationUri(parsed: ObservationUri): string {
  */
 export function parseObservationUri(value: unknown): ObservationUri | null {
   if (typeof value !== 'string') return null;
-  const cloudcli = CLOUDCLI_URI.exec(value);
-  if (cloudcli !== null) {
-    const kind = cloudcli[1] === 'session' ? 'session' : 'architecture';
-    const id = cloudcli[2]!;
-    // Both spellings parse, but the canonical string (and the DB key) stays the
-    // legacy `cloudcli://` one; 2.0 is a read widening, not a rename.
-    return { scheme: 'cloudcli', kind, id, uri: kind === 'session' ? formatSessionUri(id) : formatArchitectureUri(id) };
+  const cloud = CLOUDPIT_URI.exec(value);
+  if (cloud !== null) {
+    const kind = cloud[1] === 'session' ? 'session' : 'architecture';
+    const id = cloud[2]!;
+    return { scheme: 'cloudpit', kind, id, uri: kind === 'session' ? formatSessionUri(id) : formatArchitectureUri(id) };
   }
   const initiative = QUAY_INITIATIVE_URI.exec(value);
   if (initiative !== null) {
@@ -112,3 +115,13 @@ export function parseObservationUri(value: unknown): ObservationUri | null {
   }
   return null;
 }
+
+/**
+ * Maps an accepted object address onto its canonical `cloudpit://` form; a `quay://` address (or
+ * an unparseable value) is returned verbatim. Consumers: the observation store's row mapping and
+ * the wall's join keys.
+ */
+export function canonicalObservationUri(value: string): string {
+  const parsed = parseObservationUri(value);
+  return parsed === null ? value : parsed.uri;
+}

package/server/modules/observation/observation.routes.ts

@@ -53,7 +53,7 @@ function invalidRequest(message: string): AppError {
 function requireBodyUri(body: unknown): string {
   const uri = body !== null && typeof body === 'object' ? (body as Record<string, unknown>).uri : undefined;
   if (parseObservationUri(uri) === null) {
-    throw invalidRequest('`uri` must be one of cloudcli://session/<id>, cloudcli://architecture/<id>, quay://<id>/board');
+    throw invalidRequest('`uri` must be one of cloudpit://session/<id>, cloudpit://architecture/<id>, quay://<id>/board');
   }
   return uri as string;
 }

package/server/modules/observation/project-truth.ts

@@ -35,7 +35,7 @@ import type { ObservedStatus } from './observation-store.js';
 
 /** One project as the producer addresses it. `fleetProjectId` is the `quay://` project segment. */
 export type ProjectTruthProjectRef = {
-  /** CloudCLI's own project id, used only to ask the quay service for a snapshot. */
+  /** Cloudpit's own project id, used only to ask the quay service for a snapshot. */
   projectId: string;
   /** Absolute project root; the deploy reader resolves its own script relative to it. */
   projectPath: string;
@@ -48,7 +48,7 @@ export type ProjectTruthProjectRef = {
   fleetProjectId: string | null;
   /**
    * The deployment target, or `null` when the project has no deployment concept. Today only
-   * CloudCLI itself does; every other project's deploy layer is `not-applicable`.
+   * Cloudpit itself does; every other project's deploy layer is `not-applicable`.
    */
   deploy: ProjectTruthDeployTarget | null;
 };
@@ -221,7 +221,7 @@ const PROJECT_TRUTH_LAYER_LABELS = {
 } as const satisfies Record<keyof ProjectTruthLayers, string>;
 
 /** The deploy layer's "no deployment concept" state, excluded from aggregation. */
-export const PROJECT_TRUTH_NOT_APPLICABLE_REASON = '该项目没有部署概念（目前只有 CloudCLI 自身有部署）';
+export const PROJECT_TRUTH_NOT_APPLICABLE_REASON = '该项目没有部署概念（目前只有 Cloudpit 自身有部署）';
 
 /** One criterion row counts as a gate only while it is a live, runnable criterion. */
 const GATE_EXCLUDED_GOAL_STATUSES = new Set(['draft', 'superseded', 'retired']);

package/server/modules/observation/session-ask-decision-answer.ts

@@ -274,7 +274,8 @@ export const SYSTEM_PROMPT = [
   '是提问时输出：{"isAsking":true,"ask":"…","situation":"…","incomplete":false,"recommendedOptionId":null,"judgeOptionId":null,"judgeReason":null,"options":[{"id":"…","label":"…","does":"…","tags":[{"kind":"consequence","text":"…"}],"source":"assistant"}]}',
   '- ask：把助手消息里真正的待决问题重述成一个问句，保留原文的限定条件；不要整段照抄。问题可能来自中段的「值得优先/下一步/是否…」清单，最后一段只是附注时也要从前面取出它。',
   '- situation：回答这个问题需要知道的情境（在做什么、卡在哪、已试过什么），只写原文有的事实。',
-  '- options：助手原文用编号或项目符号列出若干选择时，必须为每一项给出一条 option（label 用原文的选项名）；原文没有列出选择才用空数组 []。does 是选它会发生什么，tags 是后果标签（kind 用 consequence / risk / cost / benefit）。',
+  '- options：当问题只有一个选择维度（从若干互斥项里选一个）时，助手原文用编号或项目符号列出多少项就给出多少条 option（label 用原文的选项名）；原文没有列出选择才用空数组 []。does 是选它会发生什么，tags 是后果标签（kind 用 consequence / risk / cost / benefit）。',
+  '- 多个相互独立的子决定（例如「三个设计点，每个都要选 A 还是 B」）不要拆成 2N 条半方向、更不要穷举 2^N 种组合：打包成 3–5 个自洽的组合选项，每个 option 覆盖全部子决定（label 用「①…+②…+③…」这种合取写法，does 写清每个子决定的取值）；优先保留助手自己讨论过或最可能被选的组合，并含「全部保持现状」「全部按助手建议推进」这类自然端点。',
   '- 是/否提问：当助手消息是「是否要…」「要不要…」「要我…吗」「Should I…?」这类只能答是或否的问题、且原文没有列出选项时，给出两个 option：id 分别为 "yes"（label 「是」）和 "no"（label 「否」），各写一句 does 与一个 consequence 标签。',
   '- recommendedOptionId：仅当助手原文明确推荐了某个选项时填它的 id；原文没有推荐就填 null。',
   '- judgeOptionId：当原文没有明确推荐时，从 options 里挑出最可能被选的一项填它的 id（是/否题填 "yes" 或 "no"）；原文已有明确推荐时必须填 null，不得覆盖助手的推荐。',

package/server/modules/observation/session-digest-llm.ts

@@ -43,6 +43,7 @@ import { readSessionAskEventWriterPort } from '@/shared/ports/session-ask-events
 
 import type { ObservedObject, ObservationStore } from './observation-store.js';
 import { createObservationStore } from './observation-store.js';
+import { parseObservationUri } from './observation-uri.js';
 import { createSessionAskDecisionDigest } from './session-ask-decision-digest.js';
 import { createSessionDigestProducer } from './session-digest.producer.js';
 import type { SessionDigestProducer, SessionTurnEndEvent } from './session-digest.producer.js';
@@ -348,11 +349,16 @@ export function createSessionDigestLlmTier(deps: SessionDigestLlmTierDeps): Sess
     durationMs: number;
   }): void {
     try {
+      // The ledger names the session by its id, not by the address spelling: since 2.1 the
+      // formatter writes `cloudpit://session/<id>`, while a 2.0 row may still be the legacy
+      // `cloudcli://` one. The parser normalizes both onto the canonical address, so the id is
+      // read the same way whichever spelling 2.0/2.1 stored.
+      const parsedUri = parseObservationUri(record.object.uri);
       usageLog.write({
         type: 'observation.session-digest-llm',
         at: record.at,
         uri: record.object.uri,
-        sessionId: record.object.uri.replace(/^cloudcli:\/\/session\//, ''),
+        sessionId: parsedUri?.id ?? record.object.uri,
         model: record.model,
         state: record.state,
         ...(record.reason === undefined ? {} : { reason: record.reason }),