[PR] refactor: unify session catalog activity authority [maka]

["Astro-Han (via GitHub)" <gi...@apache.org>]

Astro-Han opened a new pull request, #3619:
URL: https://github.com/apache/maka/pull/3619

   ## Summary
   
   Make `session_catalog_projection.activity_at` the single Session catalog recency authority across Runtime Host, CLI/TUI, and Desktop.
   
   - publish one canonical `activityAt` projection and reuse its mapper across clients
   - preserve complete authoritative catalog snapshots in Desktop instead of locally merging, upserting, or patching Session rows
   - remove the redundant Session `lastUsedAt` model/protocol field and drop its legacy SQLite column through schema migration 29
   - retain only view-level transformations such as pinned grouping, current-directory partitioning, revision projection, and cross-Host composition using the canonical timestamp
   
   The Runtime Host compatibility epoch is 43 because strict Session continuity and inspection projections changed. Schema migration 29 temporarily restores the legacy column only for synthetic or interrupted pre-29 schemas that lack it, lets historical migrations complete, then removes it.
   
   ## Verification
   
   - `npm run build --workspace @maka/core`
   - `npm run build --workspace @maka/storage`
   - `npm run build --workspace @maka/runtime`
   - `npm run build --workspace @maka/runtime-host`
   - `npm run build --prefix packages/cli`
   - `npm run build --workspace @maka/ui`
   - `npm run typecheck --workspace @maka/desktop`
   - focused Storage tests: 69 passed
   - focused Runtime Host continuity and CLI Session driver tests: 95 passed
   - focused Desktop catalog, settings, revision, and UI tests: 36 passed
   - post-rebase Runtime Host protocol tests: 43 passed
   - Biome passed for all changed TypeScript, JavaScript, and JSON files
   - `git diff --check origin/main...HEAD`
   
   The full repository test suite was not run locally; CI should provide repository-wide coverage.
   
   ## Migration
   
   Schema 29 removes `session_metadata.last_used_at` after preserving the canonical catalog projection. Historical migration references remain intentionally so databases at older schema versions can advance safely before the column is dropped.
   
   ## AI use
   
   Select exactly one:
   
   - [ ] No generative tool made a substantive contribution
   - [x] Generative tooling made a substantive contribution
   
   Tool(s) and scope: Maka assisted with architecture analysis, implementation, tests, migration work, and PR drafting. The contributor must review the final diff, provenance, and commit messages before merge.
   
   ## Checklist
   
   - [x] Tests cover the change and fail without it
   - [x] Lint, format, typecheck and the affected suites pass locally
   
   Does this PR entail a change in behavior?
   
   - [x] Yes — described under Summary above
   - [ ] No
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org

Re: [PR] refactor: unify session catalog activity authority [maka]

["jackwener (via GitHub)" <gi...@apache.org>]

jackwener commented on code in PR #3619:
URL: https://github.com/apache/maka/pull/3619#discussion_r3839167082


##########
apps/desktop/src/renderer/use-session-setting-intent.ts:
##########
@@ -0,0 +1,136 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+interface SettingIntent<Value> {
+  desired: Value;
+  committed?: Value;
+  inFlight: boolean;
+}
+
+interface SessionSettingIntentOptions<Value> {
+  catalogRevision: unknown;
+  readCatalogValue(sessionId: string): Value | undefined;
+  write(sessionId: string, value: Value): Promise<boolean>;
+  refreshCatalog(): Promise<unknown>;
+  onWriteError(sessionId: string, error: unknown): void;
+}
+
+interface SessionSettingIntentController<Value> {
+  overlayBySession: Readonly<Record<string, Value>>;
+  request(sessionId: string, value: Value): Promise<boolean>;
+  clear(sessionId: string): void;
+}
+
+/**
+ * Owns the gap between a renderer setting intent, its Host commit, and the
+ * later catalog snapshot that observes that commit. Only the latest desired
+ * value is written; a committed overlay remains until the catalog confirms it.
+ */
+export function useSessionSettingIntent<Value>(
+  options: SessionSettingIntentOptions<Value>,
+): SessionSettingIntentController<Value> {
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const intentsRef = useRef(new Map<string, SettingIntent<Value>>());
+  const [overlayBySession, setOverlayBySession] = useState<Record<string, Value>>({});
+
+  const setOverlay = useCallback((sessionId: string, value: Value | undefined): void => {
+    setOverlayBySession((current) => {
+      if (value !== undefined) {
+        if (Object.is(current[sessionId], value)) return current;
+        return { ...current, [sessionId]: value };
+      }
+      if (!(sessionId in current)) return current;
+      const next = { ...current };
+      delete next[sessionId];
+      return next;
+    });
+  }, []);
+
+  const reconcile = useCallback((sessionId: string): void => {
+    const intent = intentsRef.current.get(sessionId);
+    if (!intent || intent.inFlight || intent.committed === undefined) return;
+    if (!Object.is(optionsRef.current.readCatalogValue(sessionId), intent.committed)) return;

Review Comment:
   [P2] Requiring the catalog value to equal `intent.committed` can leave an old overlay permanent after a newer legitimate Host transition. Reachable sequence: Agent → the renderer commits Plan → that catalog refresh fails, so the committed Plan overlay correctly remains → the user approves the Plan → Runtime automatically changes collaboration mode back to Agent and publishes a newer successful catalog snapshot. Because `Agent !== committed Plan`, every later reconciliation returns here and the menu continues showing Plan forever. A real hook probe stayed overlaid after the failed refresh and after a newer Agent snapshot; only a later matching Plan snapshot cleared it. The new E2Es cover failure retention and a matching renderer write, not Host-driven supersession. Retire the overlay when a successful snapshot newer than the commit is observed (while preserving latest-intent fencing), rather than waiting indefinitely for value equality; add a Plan-approval→automatic-Agent
  regression.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org

Re: [PR] refactor: unify session catalog activity authority [maka]

["Astro-Han (via GitHub)" <gi...@apache.org>]

Astro-Han commented on code in PR #3619:
URL: https://github.com/apache/maka/pull/3619#discussion_r3839299161


##########
apps/desktop/src/renderer/use-session-setting-intent.ts:
##########
@@ -0,0 +1,136 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+interface SettingIntent<Value> {
+  desired: Value;
+  committed?: Value;
+  inFlight: boolean;
+}
+
+interface SessionSettingIntentOptions<Value> {
+  catalogRevision: unknown;
+  readCatalogValue(sessionId: string): Value | undefined;
+  write(sessionId: string, value: Value): Promise<boolean>;
+  refreshCatalog(): Promise<unknown>;
+  onWriteError(sessionId: string, error: unknown): void;
+}
+
+interface SessionSettingIntentController<Value> {
+  overlayBySession: Readonly<Record<string, Value>>;
+  request(sessionId: string, value: Value): Promise<boolean>;
+  clear(sessionId: string): void;
+}
+
+/**
+ * Owns the gap between a renderer setting intent, its Host commit, and the
+ * later catalog snapshot that observes that commit. Only the latest desired
+ * value is written; a committed overlay remains until the catalog confirms it.
+ */
+export function useSessionSettingIntent<Value>(
+  options: SessionSettingIntentOptions<Value>,
+): SessionSettingIntentController<Value> {
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const intentsRef = useRef(new Map<string, SettingIntent<Value>>());
+  const [overlayBySession, setOverlayBySession] = useState<Record<string, Value>>({});
+
+  const setOverlay = useCallback((sessionId: string, value: Value | undefined): void => {
+    setOverlayBySession((current) => {
+      if (value !== undefined) {
+        if (Object.is(current[sessionId], value)) return current;
+        return { ...current, [sessionId]: value };
+      }
+      if (!(sessionId in current)) return current;
+      const next = { ...current };
+      delete next[sessionId];
+      return next;
+    });
+  }, []);
+
+  const reconcile = useCallback((sessionId: string): void => {
+    const intent = intentsRef.current.get(sessionId);
+    if (!intent || intent.inFlight || intent.committed === undefined) return;
+    if (!Object.is(optionsRef.current.readCatalogValue(sessionId), intent.committed)) return;

Review Comment:
   Closing this out: verified fixed on head `5fde3d4951d5bfbcd91518ebc9e96b33616f4d13` by an independent reviewer who was deliberately given this finding only as a hypothesis to test, not as a conclusion to confirm.
   
   The overlay now clears via a `catalogRevision` causal fence (`use-session-setting-intent.ts:70-76,109`) instead of requiring the catalog value to equal the committed Plan. A failed refresh does not bump the revision, so a later successful Agent snapshot carries a higher revision and clears the overlay — which is exactly the sequence that used to strand it. `session-setting-intent.test.ts` covers that path directly: successful write, refresh throws, then a revision-1 Agent snapshot.
   
   So the trigger was not relocated; the condition it depended on was replaced. Marking resolved.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org

Re: [PR] refactor: unify session catalog activity authority [maka]

["Astro-Han (via GitHub)" <gi...@apache.org>]

Astro-Han merged PR #3619:
URL: https://github.com/apache/maka/pull/3619


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org