feat(spec): declare organization_id on ApprovalRequestRow and ApprovalActionRow (#10465)

* feat(spec): declare organization_id on ApprovalRequestRow and ApprovalActionRow

The approval service stamps the tenancy placement on every row it inserts
(and returns it on request-row reads), but the published contract types
omitted the field, forcing consumers to cast past the contract. Type-only
widening per the maintainer ruling on #10331 (option A).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016gcKVsiywU9CcS96S5t9qD

* test(spec): use expectTypeOf idiom for the organization_id pins

The Expect/Equals helper aliases trip noUnusedLocals (TS6196) under the
test-typecheck ratchet; expectTypeOf is the live idiom in spec tests
(api/protocol.test.ts).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016gcKVsiywU9CcS96S5t9qD

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: Jack Q

.changeset/approval-row-organization-id.md

@@ -0,0 +1,10 @@
+---
+"@objectstack/spec": minor
+---
+
+Declare `organization_id?: string | null` on `ApprovalRequestRow` and
+`ApprovalActionRow` (#10331). The approval service has always stamped the
+tenancy placement on the rows it inserts — and returns it on request-row
+reads — but the published contract types omitted the field, so consumers had
+to cast past the contract to reach it. Type-only widening: one declared
+optional field per row, no runtime change.

packages/plugins/plugin-approvals/src/approver-cross-org.integration.test.ts

@@ -129,6 +129,9 @@ describe('ADR-0105 D9 — cross-org approver targeting through ApprovalService',
     // This is the whole point of the split: targeting must not relocate the
     // request into the approver's organization, or the plant would lose its own
     // audit trail to the group.
+    // (#10331 has since declared `organization_id` on the contract row types,
+    // so returned rows carry it typed; these persisted-row reads stay because
+    // storage placement across all three tables is exactly what's pinned here.)
     expect(engine._tables['sys_approval_request'][0].organization_id).toBe('o_plant');
     expect(engine._tables['sys_approval_approver'][0].organization_id).toBe('o_plant');
     expect(engine._tables['sys_approval_action'][0].organization_id).toBe('o_plant');

packages/spec/src/contracts/approval-service.test.ts

@@ -0,0 +1,56 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// [#10331] `organization_id` existed on the wire (plugin-approvals stamps it
+// on insert and `rowFromRequest` returns it) but not on the published row
+// types, so every consumer cast past the contract to reach it. These pins keep
+// the declaration honest: the field must stay readable off the DECLARED types
+// without a cast, at the exact optional-nullable shape the write expression
+// produces (`context.organizationId ?? context.tenantId ?? input.organizationId
+// ?? null` — a resolved org id, or `null` when none resolved, or absent on
+// rows written before stamping existed).
+
+import { describe, it, expect, expectTypeOf } from 'vitest';
+import type { ApprovalActionRow, ApprovalRequestRow } from './approval-service';
+
+describe('approval row organization_id declaration (#10331)', () => {
+    it('is readable off ApprovalRequestRow without a cast, at the stamped shape', () => {
+        // Reading the property off the declared type — no `as`, no indexing
+        // through `any`. This line failing to compile is the regression.
+        const read = (row: ApprovalRequestRow): string | null | undefined => row.organization_id;
+
+        // Exactly `string | null | undefined`: `null` is the write path's
+        // "no org resolved" value and must not be silently narrowed away.
+        expectTypeOf<ApprovalRequestRow['organization_id']>().toEqualTypeOf<string | null | undefined>();
+
+        // Optional: a row written before the stamp existed still satisfies the
+        // type (this object literal fails to compile if the field is required).
+        const preStamp: ApprovalRequestRow = {
+            id: 'req_1',
+            process_name: 'flow:review',
+            object_name: 'showcase_project',
+            record_id: 'rec_1',
+            status: 'pending',
+        };
+        expect(read(preStamp)).toBeUndefined();
+        expect(read({ ...preStamp, organization_id: null })).toBeNull();
+        expect(read({ ...preStamp, organization_id: 'o_plant' })).toBe('o_plant');
+    });
+
+    it('is readable off ApprovalActionRow without a cast, at the stamped shape', () => {
+        // Every `sys_approval_action` insert site stamps the owning request's
+        // org on the persisted row; see the field's docblock for the read-path
+        // caveat (the service's `rowFromAction` mapping does not surface it).
+        const read = (row: ApprovalActionRow): string | null | undefined => row.organization_id;
+
+        expectTypeOf<ApprovalActionRow['organization_id']>().toEqualTypeOf<string | null | undefined>();
+
+        const minimal: ApprovalActionRow = {
+            id: 'aact_1',
+            request_id: 'req_1',
+            action: 'submit',
+        };
+        expect(read(minimal)).toBeUndefined();
+        expect(read({ ...minimal, organization_id: null })).toBeNull();
+        expect(read({ ...minimal, organization_id: 'o_plant' })).toBe('o_plant');
+    });
+});

packages/spec/src/contracts/approval-service.ts

@@ -83,6 +83,22 @@ export const APPROVAL_STATUS_LABELS = {
 /** Live request row. */
 export interface ApprovalRequestRow {
   id: string;
+  /**
+   * Tenancy placement stamp (#10331): the organization the request belongs
+   * to. `plugin-approvals` writes it on the inserted `sys_approval_request`
+   * row at submit time — resolved as
+   * `context.organizationId ?? context.tenantId ?? input.organizationId ?? null`
+   * — and its read mapping (`rowFromRequest`) returns it on every service
+   * read. The field was always on the wire; this declaration types it so
+   * consumers (and tests pinning org placement) read it without casting past
+   * the contract.
+   *
+   * Optional-nullable: rows written before the stamp existed carry no value,
+   * and a submit whose context resolves no org stamps `null` — "owned by no
+   * organization", which org-scoped reads treat as globally visible rather
+   * than tenant-owned.
+   */
+  organization_id?: string | null;
   /** Origin of the request — `flow:<flowName|nodeId>` for node-driven approvals. */
   process_name: string;
   object_name: string;
@@ -364,6 +380,20 @@ export interface ApprovalActionAttachment {
 export interface ApprovalActionRow {
   id: string;
   request_id: string;
+  /**
+   * Tenancy placement stamp (#10331), same semantics as
+   * {@link ApprovalRequestRow.organization_id}: every `sys_approval_action`
+   * insert site in `plugin-approvals` stamps the owning request's org (or
+   * `null` when none resolved), so the persisted row always carries it.
+   *
+   * Read-path caveat, measured at declaration time: the service's
+   * `rowFromAction` mapping does not surface it, so rows returned by
+   * `listActions` currently omit the field — it is populated when a persisted
+   * row is read directly off the engine (the pattern org-placement tests
+   * use). Declared optional-nullable for that gap as well as for pre-stamp
+   * rows.
+   */
+  organization_id?: string | null;
   step_name?: string;
   step_index?: number;
   action: ApprovalActionKind;