@haneinfo/state-machine 0.7.1 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,37 +1,58 @@
1
- # @haneinfo/state-machine
2
-
3
- See [agent-guide.md](agent-guide.md) for integration details.
4
-
5
- ## Instance readers and stored query values
6
-
7
- Reads allow the submitter, holders of `state-machine:instance:read`, or an instance reader grant.
8
- ADMIN continues to use existing RBAC. `mine=true` still means submitter ownership. Number lookups
9
- apply the same rule before pagination.
10
-
11
- `StateMachineReaderGrants.grantAssigned(instanceId, userIds, tx)` is a grant-only service exported
12
- by StateMachineModule. Assignment injects it and supplies the task transaction; grants use
13
- `createMany({ skipDuplicates: true })` (PostgreSQL `ON CONFLICT DO NOTHING`). There is no revoke
14
- operation or additional read port. Custom stores must implement `grantReaders`, `isReader`, and
15
- `readableBy` instance/number filters. Apps must migrate the Prisma fragment and backfill existing
16
- tasks before upgrading. The `(instance_id, user_id)` primary key supports indexed reader lookups;
17
- the separate `user_id` index supports user-led scans.
18
-
19
- ```sql
20
- INSERT INTO state_machine_instance_readers (instance_id, user_id, reason)
21
- SELECT DISTINCT instance_id, assignee_id, 'ASSIGNED'
22
- FROM assignment_tasks
23
- ON CONFLICT (instance_id, user_id) DO NOTHING;
24
- ```
25
-
26
- Top-level text, textarea, number, date and datetime formula fields can be declared in
27
- `spec.listView.fields`. Queries read stored results through the ordinary JSONB path. Queries never
28
- recompute formulas or backfill missing historical values. Select, switch, nested and container
29
- fields remain unsupported.
30
-
31
- ## Date comparisons
32
-
33
- GT/GTE/LT/LTE compare numbers, valid calendar dates (YYYY-MM-DD), or timezone-qualified datetimes
34
- (YYYY-MM-DDTHH:mm:ss with optional fractional seconds and Z or +/-HH:mm). Both operands must have
35
- the same category. Dates use calendar order; datetimes compare UTC instants at millisecond precision.
36
- Invalid dates, mixed categories and empty operands yield false. EQ/NEQ/IN retain strict scalar equality;
37
- matching instants with different textual offsets are still unequal for those operators.
1
+ # @haneinfo/state-machine
2
+
3
+ See [agent-guide.md](agent-guide.md) for integration details.
4
+
5
+ ## Instance readers and stored query values
6
+
7
+ Reads allow the submitter, holders of `state-machine:instance:read`, or an instance reader grant.
8
+ ADMIN continues to use existing RBAC. `mine=true` still means submitter ownership. Number lookups
9
+ apply the same rule before pagination.
10
+
11
+ `StateMachineReaderGrants.grantAssigned(instanceId, userIds, tx)` is a grant-only service exported
12
+ by StateMachineModule. Assignment injects it and supplies the task transaction; grants use
13
+ `createMany({ skipDuplicates: true })` (PostgreSQL `ON CONFLICT DO NOTHING`). There is no revoke
14
+ operation or additional read port. Custom stores must implement `grantReaders`, `isReader`, and
15
+ `readableBy` instance/number filters. Apps must migrate the Prisma fragment and backfill existing
16
+ tasks before upgrading. The `(instance_id, user_id)` primary key supports indexed reader lookups;
17
+ the separate `user_id` index supports user-led scans.
18
+
19
+ ```sql
20
+ INSERT INTO state_machine_instance_readers (instance_id, user_id, reason)
21
+ SELECT DISTINCT instance_id, assignee_id, 'ASSIGNED'
22
+ FROM assignment_tasks
23
+ ON CONFLICT (instance_id, user_id) DO NOTHING;
24
+ ```
25
+
26
+ Top-level text, textarea, number, date and datetime formula fields can be declared in
27
+ `spec.listView.fields`. Queries read stored results through the ordinary JSONB path. Queries never
28
+ recompute formulas or backfill missing historical values. Select, switch, nested and container
29
+ fields remain unsupported.
30
+
31
+ ## Date comparisons
32
+
33
+ GT/GTE/LT/LTE compare numbers, valid calendar dates (YYYY-MM-DD), or timezone-qualified datetimes
34
+ (YYYY-MM-DDTHH:mm:ss with optional fractional seconds and Z or +/-HH:mm). Both operands must have
35
+ the same category. Dates use calendar order; datetimes compare UTC instants at millisecond precision.
36
+ Invalid dates, mixed categories and empty operands yield false. EQ/NEQ/IN retain strict scalar equality;
37
+ matching instants with different textual offsets are still unequal for those operators.
38
+
39
+ ## Instance privacy and submitter names
40
+
41
+ All person-facing instance reads (detail including history, available transitions and exact number lookup) return `INSTANCE_NOT_FOUND`, HTTP 404, message `Instance not found`, with no suggestion for both missing and unreadable instances. No read permission name is exposed. USER transitions and data updates check readability before revision, state and write authorization; readable users missing the write/business permission still receive 403. Submitter ownership, effective instance:read and permanent reader grants are unchanged. Internal `get`/`history` remain trusted mechanism APIs without a person parameter; there is no delete endpoint.
42
+
43
+ Authorized detail, instance list and numbering reads include `submitterName: string | null`. Optional identity-store `findActiveNamesByIds` resolves unique submitter ids once per result batch. Missing, inactive and deleted identities, absent identity capability and older providers return null without per-row fallbacks. No schema migration or people-lookup HTTP route is added. Numbering MCP wraps names in `$userContent`; exact unreadable/missing numbers return the same error, while recent-number lists still filter before paging.
44
+
45
+ ## Delegated Assignment attribution
46
+
47
+ ASSIGNMENT triggers may include optional actingUserId and onBehalfOfId. Existing userId and
48
+ triggerUserId remain the actual actor. Attribution is persisted in the existing transition decision
49
+ JSON and exposed as optional history fields, including getFor's embedded history. Notification
50
+ outcomes merge with this metadata instead of replacing it. No history schema migration is needed.
51
+ The decision remains draft (202610-6b1f). Assignment owns delegation validity and response policy.
52
+
53
+ When the resolver is installed, StateMachine takes its optional shared transaction advisory lock
54
+ before instance creation or any instance row lock/write. Delegation creation/revocation takes the
55
+ exclusive lock on the same key. Normal instance transactions remain concurrent; a graph mutation
56
+ briefly blocks new instance writers until its backfill/cancellation commits. This closes the race
57
+ where creation and state entry could otherwise miss each other's uncommitted rows. The advisory lock always precedes instance locks; task CAS and delegation-row shared locks
58
+ remain inside that transaction. No extra table or worker is added.