(maka) branch main updated: refactor(storage): centralize safe persisted identifiers (#4931)

[zh...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

me2seeks pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/maka.git


The following commit(s) were added to refs/heads/main by this push:
     new 6974c479b0 refactor(storage): centralize safe persisted identifiers (#4931)
6974c479b0 is described below

commit 6974c479b05a52bcdbc79ac536a99c5b26e0681c
Author: seekskyworld <14...@users.noreply.github.com>
AuthorDate: Tue Sep 8 09:09:05 2026 +0800

    refactor(storage): centralize safe persisted identifiers (#4931)
    
    Signed-off-by: seekskyworld <dj...@gmail.com>
---
 packages/storage/src/__tests__/storage-id.test.ts  | 49 ++++++++++++++++++++++
 packages/storage/src/goal-authority.ts             |  3 +-
 packages/storage/src/interaction-store.ts          |  4 +-
 packages/storage/src/runtime-event-invariants.ts   |  5 +--
 packages/storage/src/session-bundle-policy.ts      |  3 +-
 packages/storage/src/session-copy-cleanup.ts       |  3 +-
 .../{runtime-event-invariants.ts => storage-id.ts} | 24 +++++------
 7 files changed, 69 insertions(+), 22 deletions(-)

diff --git a/packages/storage/src/__tests__/storage-id.test.ts b/packages/storage/src/__tests__/storage-id.test.ts
new file mode 100644
index 0000000000..7b29ba6c3e
--- /dev/null
+++ b/packages/storage/src/__tests__/storage-id.test.ts
@@ -0,0 +1,49 @@
+/*
+ * 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 assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { assertSafeStorageId, isSafeStorageId } from '../storage-id.js';
+
+test('accepts the complete safe storage identifier boundary', () => {
+  assert.equal(isSafeStorageId('a'), true);
+  assert.equal(isSafeStorageId('A0_-'), true);
+  assert.equal(isSafeStorageId('x'.repeat(128)), true);
+});
+
+test('rejects unsafe storage identifier values', () => {
+  for (const value of [
+    '',
+    'x'.repeat(129),
+    ' leading',
+    'trailing ',
+    'nested/path',
+    'punctuation.',
+    undefined,
+    null,
+    42,
+    {},
+  ]) {
+    assert.equal(isSafeStorageId(value), false, `expected rejection for ${String(value)}`);
+  }
+  assert.throws(() => assertSafeStorageId('bad/id', 'custom storage id error'), {
+    name: 'TypeError',
+    message: 'custom storage id error',
+  });
+});
diff --git a/packages/storage/src/goal-authority.ts b/packages/storage/src/goal-authority.ts
index f65952687a..b3b344d6db 100644
--- a/packages/storage/src/goal-authority.ts
+++ b/packages/storage/src/goal-authority.ts
@@ -28,6 +28,7 @@ import {
   StorageRootAuthorityError,
   type StorageRootLease,
 } from './root-authority.js';
+import { assertSafeStorageId } from './storage-id.js';
 
 const writerBrand: unique symbol = Symbol('InteractiveGoalAuthorityWriter');
 const writers = new WeakSet<object>();
@@ -300,5 +301,5 @@ function cloneSnapshot(snapshot: GoalAuthoritySnapshot): GoalAuthoritySnapshot {
 }
 
 function requireId(value: string, label: string): void {
-  if (!/^[A-Za-z0-9_-]{1,128}$/.test(value)) throw new TypeError(`${label} identity is invalid`);
+  assertSafeStorageId(value, `${label} identity is invalid`);
 }
diff --git a/packages/storage/src/interaction-store.ts b/packages/storage/src/interaction-store.ts
index 3aa5b4195c..9bd514a85f 100644
--- a/packages/storage/src/interaction-store.ts
+++ b/packages/storage/src/interaction-store.ts
@@ -46,8 +46,8 @@ import {
   acquireOperationalStateDatabase,
   type OperationalStateDatabaseLease,
 } from './operational-state-store.js';
+import { isSafeStorageId } from './storage-id.js';
 
-const SAFE_ID = /^[A-Za-z0-9_-]{1,128}$/;
 const REMEMBER_SCOPE_ID = /^[0-9a-f]{64}$/;
 export const STORED_INTERACTION_REQUEST_MAX_BYTES = 20 * 1024;
 export const STORED_INTERACTION_OUTCOME_MAX_BYTES = 12 * 1024;
@@ -788,7 +788,7 @@ function assertId(
   source: DecodeSource = 'input',
   message = 'Invalid Interaction identity',
 ): string {
-  if (typeof value !== 'string' || !SAFE_ID.test(value)) decodeFailure(source, message);
+  if (!isSafeStorageId(value)) decodeFailure(source, message);
   return value;
 }
 
diff --git a/packages/storage/src/runtime-event-invariants.ts b/packages/storage/src/runtime-event-invariants.ts
index 4b0f913f0e..56f3811cae 100644
--- a/packages/storage/src/runtime-event-invariants.ts
+++ b/packages/storage/src/runtime-event-invariants.ts
@@ -18,11 +18,10 @@
  */
 
 import type { RuntimeEvent } from '@maka/core/runtime-event';
-
-const SAFE_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+import { isSafeStorageId } from './storage-id.js';
 
 export function isRuntimeStorageSafeId(value: string): boolean {
-  return SAFE_ID_PATTERN.test(value);
+  return isSafeStorageId(value);
 }
 
 export function immutableSteeringMessageId(event: RuntimeEvent): string | undefined {
diff --git a/packages/storage/src/session-bundle-policy.ts b/packages/storage/src/session-bundle-policy.ts
index f0385d9997..d5e19aa834 100644
--- a/packages/storage/src/session-bundle-policy.ts
+++ b/packages/storage/src/session-bundle-policy.ts
@@ -38,6 +38,7 @@ import {
   acquireOperationalStateDatabase,
   OPERATIONAL_STATE_DATABASE_NAME,
 } from './operational-state-store.js';
+import { isSafeStorageId } from './storage-id.js';
 
 export const SESSION_BUNDLE_STATE_ENTRIES = [
   'artifacts',
@@ -404,7 +405,7 @@ function assertRootsSeparate(left: string, right: string, allowSame: boolean): v
 }
 
 function assertSafeSessionId(sessionId: string): void {
-  if (!/^[A-Za-z0-9_-]{1,128}$/.test(sessionId)) {
+  if (!isSafeStorageId(sessionId)) {
     throw new SessionBundleExportError('invalid_root', `Invalid session id: ${sessionId}`);
   }
 }
diff --git a/packages/storage/src/session-copy-cleanup.ts b/packages/storage/src/session-copy-cleanup.ts
index a1cf6dd62b..4b309675d0 100644
--- a/packages/storage/src/session-copy-cleanup.ts
+++ b/packages/storage/src/session-copy-cleanup.ts
@@ -27,6 +27,7 @@ import {
   type ProcessLifetimeOwner,
   type ProcessLifetimeRecoveryClaim,
 } from './process-lifetime-owner.js';
+import { isSafeStorageId } from './storage-id.js';
 
 export interface SessionCopyCreationLease {
   sessionId: string;
@@ -534,7 +535,7 @@ function samePersistedCreation(
 function normalizeSessionId(value: unknown): string {
   if (typeof value !== 'string') throw new Error('Invalid Session copy id');
   const normalized = value.trim();
-  if (!/^[A-Za-z0-9_-]{1,128}$/.test(normalized)) {
+  if (!isSafeStorageId(normalized)) {
     throw new Error('Invalid Session copy id');
   }
   return normalized;
diff --git a/packages/storage/src/runtime-event-invariants.ts b/packages/storage/src/storage-id.ts
similarity index 58%
copy from packages/storage/src/runtime-event-invariants.ts
copy to packages/storage/src/storage-id.ts
index 4b0f913f0e..f14f7fabb4 100644
--- a/packages/storage/src/runtime-event-invariants.ts
+++ b/packages/storage/src/storage-id.ts
@@ -17,21 +17,17 @@
  * under the License.
  */
 
-import type { RuntimeEvent } from '@maka/core/runtime-event';
+const SAFE_STORAGE_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
 
-const SAFE_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
-
-export function isRuntimeStorageSafeId(value: string): boolean {
-  return SAFE_ID_PATTERN.test(value);
+/** Returns whether a value can safely be used as a persisted storage identity. */
+export function isSafeStorageId(value: unknown): value is string {
+  return typeof value === 'string' && SAFE_STORAGE_ID_PATTERN.test(value);
 }
 
-export function immutableSteeringMessageId(event: RuntimeEvent): string | undefined {
-  const messageId = event.refs?.providerEventId;
-  return event.partial === false &&
-    typeof messageId === 'string' &&
-    isRuntimeStorageSafeId(messageId) &&
-    event.content?.kind === 'text' &&
-    event.content.steering === true
-    ? messageId
-    : undefined;
+/** Throws a TypeError unless the value is a safe persisted storage identity. */
+export function assertSafeStorageId(
+  value: unknown,
+  message = 'Storage identity is invalid',
+): asserts value is string {
+  if (!isSafeStorageId(value)) throw new TypeError(message);
 }


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