@haneinfo/state-machine 0.10.0 → 0.12.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 +120 -108
- package/agent-guide.md +360 -348
- package/dist/instance-access.controller.d.ts +1 -0
- package/dist/instance-access.controller.d.ts.map +1 -1
- package/dist/instance-access.service.d.ts +3 -2
- package/dist/instance-access.service.d.ts.map +1 -1
- package/dist/instance-access.service.js +7 -5
- package/dist/instance-access.service.js.map +1 -1
- package/dist/mcp-tools.js +1 -1
- package/dist/mcp-tools.js.map +1 -1
- package/dist/store.d.ts +1 -1
- package/dist/store.d.ts.map +1 -1
- package/dist/store.js.map +1 -1
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -1,108 +1,120 @@
|
|
|
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.
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
## Instance access lists (draft implementation)
|
|
62
|
-
|
|
63
|
-
Implemented against draft decision 202610-c8e3; the decision remains draft. This section supersedes
|
|
64
|
-
the earlier reader-only model and human transition eligibility. Upgrade the affected
|
|
65
|
-
mechanisms together and apply the App migration before starting the new runtime. The maintainer
|
|
66
|
-
selected source-specific uniqueness: `(instanceId, principalType, principalId, source)`. Existing
|
|
67
|
-
model/table names are retained. `principalType` is USER or ROLE; `principalId` is a user id or role
|
|
68
|
-
machine name; `level` is READ or WRITE; `source` is ASSIGNED, DELEGATED or GRANTED. Each row also
|
|
69
|
-
has nullable grantedBy and createdAt. Indexes cover instanceId and (principalType, principalId).
|
|
70
|
-
Permanent ASSIGNED/DELEGATED entries are READ and survive every task/delegation status. Manual
|
|
71
|
-
GRANTED entries coexist with them; removing GRANTED never removes permanent readership.
|
|
72
|
-
|
|
73
|
-
All instance reads use submitter, effective state-machine:instance:read, or a matching USER/ROLE
|
|
74
|
-
entry. Roles come from RBAC authorizationOfUser once per query, passed into persistence; no direct
|
|
75
|
-
RBAC-table joins. WRITE also requires an existing readable instance, then submitter, effective
|
|
76
|
-
state-machine:instance:write, or matching WRITE. Human transitions still check their declared
|
|
77
|
-
business permission. Assignment/Timer transition authorization is unchanged. Unreadable instances
|
|
78
|
-
return INSTANCE_NOT_FOUND/404; readable callers without write/manage eligibility receive 403.
|
|
79
|
-
|
|
80
|
-
Only the submitter or state-machine:instance:admin can manage access; instance administrators can
|
|
81
|
-
manage any instance list. Grantees cannot regrant. InteractiveAuthGuard protects GET/PUT
|
|
82
|
-
/state-machine-instances/:id/access and DELETE /state-machine-instances/:id/access/:principalType/:principalId.
|
|
83
|
-
PUT targets GRANTED only, never changes permanent rows. DELETE removes GRANTED if present; a
|
|
84
|
-
permanent-only target returns ACCESS_NOT_MANAGEABLE/409. Missing manual targets are idempotent.
|
|
85
|
-
GET returns sources, levels, principalName and grantedByName; user names share one authorized
|
|
86
|
-
findActiveNamesByIds batch, role display labels share one RBAC lookup, unavailable names are null.
|
|
87
|
-
Names are plain text. maxGrantedAccess defaults to 100. Only active users or existing roles can be
|
|
88
|
-
granted; the submitter cannot receive a USER grant. Errors include ACCESS_PRINCIPAL_INVALID/400,
|
|
89
|
-
ACCESS_LIMIT_EXCEEDED/409 and ACCESS_NOT_MANAGEABLE/409. Repeated equal grants have no effects.
|
|
90
|
-
|
|
91
|
-
StateMachineMcpTools.registerInto now also registers list_instance_access using <namespace>:instance:read.
|
|
92
|
-
It returns items in $userContent and offers no grant/remove tools. Changed individual grants notify
|
|
93
|
-
with state-machine-access:<historyId>; equal retries do not notify again. Role grants and removals
|
|
94
|
-
never notify. Missing inbox capability skips delivery. Actual inbox failures roll back the mutation.
|
|
95
|
-
ACCESS history uses the existing decision JSON and emits state-machine.access.recorded in the
|
|
96
|
-
same transaction; collaboration adds ACCESS to its existing SQL timeline union. State, revision and
|
|
97
|
-
transition events do not change for access mutations. List/export counts and pagination include
|
|
98
|
-
personal and role access in one parameterized EXISTS; snapshot exports abort on role-name changes.
|
|
99
|
-
|
|
100
|
-
Migration SQL ships at @haneinfo/state-machine/prisma/instance-access.sql. It renames user_id to
|
|
101
|
-
principal_id and reason to source, preserves created_at, adds principal_type/level/granted_by,
|
|
102
|
-
converts legacy rows to USER/READ and ASSIGNED (recognized delegation becomes DELEGATED), and
|
|
103
|
-
backfills every assignment task regardless of status. It expects the Assignment delegation columns;
|
|
104
|
-
Apps without Assignment/Delegation must omit the corresponding task queries/backfill. Do not reset
|
|
105
|
-
an existing database. See the package repository validation/equipment-loan/instance-access/report.md
|
|
106
|
-
for adoption evidence and the explicitly selected uniqueness adjustment; no decision text is changed.
|
|
107
|
-
|
|
108
|
-
Configure runtime.stateMachine.maxGrantedAccess (positive integer, default 100). Apply prisma/instance-access.sql in your App migration before upgrading. Custom StateMachineStore implementations must implement listAccess, putGranted and deleteGranted and accept optional roles/source/level in reader methods. The new optional RBAC role-label lookup requires plugin API 1.14.0.
|
|
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.
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
## Instance access lists (draft implementation)
|
|
62
|
+
|
|
63
|
+
Implemented against draft decision 202610-c8e3; the decision remains draft. This section supersedes
|
|
64
|
+
the earlier reader-only model and human transition eligibility. Upgrade the affected
|
|
65
|
+
mechanisms together and apply the App migration before starting the new runtime. The maintainer
|
|
66
|
+
selected source-specific uniqueness: `(instanceId, principalType, principalId, source)`. Existing
|
|
67
|
+
model/table names are retained. `principalType` is USER or ROLE; `principalId` is a user id or role
|
|
68
|
+
machine name; `level` is READ or WRITE; `source` is ASSIGNED, DELEGATED or GRANTED. Each row also
|
|
69
|
+
has nullable grantedBy and createdAt. Indexes cover instanceId and (principalType, principalId).
|
|
70
|
+
Permanent ASSIGNED/DELEGATED entries are READ and survive every task/delegation status. Manual
|
|
71
|
+
GRANTED entries coexist with them; removing GRANTED never removes permanent readership.
|
|
72
|
+
|
|
73
|
+
All instance reads use submitter, effective state-machine:instance:read, or a matching USER/ROLE
|
|
74
|
+
entry. Roles come from RBAC authorizationOfUser once per query, passed into persistence; no direct
|
|
75
|
+
RBAC-table joins. WRITE also requires an existing readable instance, then submitter, effective
|
|
76
|
+
state-machine:instance:write, or matching WRITE. Human transitions still check their declared
|
|
77
|
+
business permission. Assignment/Timer transition authorization is unchanged. Unreadable instances
|
|
78
|
+
return INSTANCE_NOT_FOUND/404; readable callers without write/manage eligibility receive 403.
|
|
79
|
+
|
|
80
|
+
Only the submitter or state-machine:instance:admin can manage access; instance administrators can
|
|
81
|
+
manage any instance list. Grantees cannot regrant. InteractiveAuthGuard protects GET/PUT
|
|
82
|
+
/state-machine-instances/:id/access and DELETE /state-machine-instances/:id/access/:principalType/:principalId.
|
|
83
|
+
PUT targets GRANTED only, never changes permanent rows. DELETE removes GRANTED if present; a
|
|
84
|
+
permanent-only target returns ACCESS_NOT_MANAGEABLE/409. Missing manual targets are idempotent.
|
|
85
|
+
GET returns sources, levels, principalName and grantedByName; user names share one authorized
|
|
86
|
+
findActiveNamesByIds batch, role display labels share one RBAC lookup, unavailable names are null.
|
|
87
|
+
Names are plain text. maxGrantedAccess defaults to 100. Only active users or existing roles can be
|
|
88
|
+
granted; the submitter cannot receive a USER grant. Errors include ACCESS_PRINCIPAL_INVALID/400,
|
|
89
|
+
ACCESS_LIMIT_EXCEEDED/409 and ACCESS_NOT_MANAGEABLE/409. Repeated equal grants have no effects.
|
|
90
|
+
|
|
91
|
+
StateMachineMcpTools.registerInto now also registers list_instance_access using <namespace>:instance:read.
|
|
92
|
+
It returns items in $userContent and offers no grant/remove tools. Changed individual grants notify
|
|
93
|
+
with state-machine-access:<historyId>; equal retries do not notify again. Role grants and removals
|
|
94
|
+
never notify. Missing inbox capability skips delivery. Actual inbox failures roll back the mutation.
|
|
95
|
+
ACCESS history uses the existing decision JSON and emits state-machine.access.recorded in the
|
|
96
|
+
same transaction; collaboration adds ACCESS to its existing SQL timeline union. State, revision and
|
|
97
|
+
transition events do not change for access mutations. List/export counts and pagination include
|
|
98
|
+
personal and role access in one parameterized EXISTS; snapshot exports abort on role-name changes.
|
|
99
|
+
|
|
100
|
+
Migration SQL ships at @haneinfo/state-machine/prisma/instance-access.sql. It renames user_id to
|
|
101
|
+
principal_id and reason to source, preserves created_at, adds principal_type/level/granted_by,
|
|
102
|
+
converts legacy rows to USER/READ and ASSIGNED (recognized delegation becomes DELEGATED), and
|
|
103
|
+
backfills every assignment task regardless of status. It expects the Assignment delegation columns;
|
|
104
|
+
Apps without Assignment/Delegation must omit the corresponding task queries/backfill. Do not reset
|
|
105
|
+
an existing database. See the package repository validation/equipment-loan/instance-access/report.md
|
|
106
|
+
for adoption evidence and the explicitly selected uniqueness adjustment; no decision text is changed.
|
|
107
|
+
|
|
108
|
+
Configure runtime.stateMachine.maxGrantedAccess (positive integer, default 100). Apply prisma/instance-access.sql in your App migration before upgrading. Custom StateMachineStore implementations must implement listAccess, putGranted and deleteGranted and accept optional roles/source/level in reader methods. The new optional RBAC role-label lookup requires plugin API 1.14.0.
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
## Access management eligibility (draft 202610-e2a9)
|
|
112
|
+
|
|
113
|
+
GET /state-machine-instances/:id/access adds canManage: boolean alongside the unchanged items.
|
|
114
|
+
The service shares its submitter/instance-admin eligibility calculation with PUT/DELETE; readers
|
|
115
|
+
can inspect but cannot regrant access. list_instance_access adds the same canManage next to its
|
|
116
|
+
existing wrapped items. It remains read-only. No database or plugin-api contract changes apply.
|
|
117
|
+
|
|
118
|
+
## Optional attachments (draft decision 202610-5f3b)
|
|
119
|
+
|
|
120
|
+
Attachment activity uses existing history with triggerType ATTACHMENT and optional decision.attachment (action, id, plain-text fileName). No storage keys, state/revision changes or notifications are introduced. Collaboration classifies these history rows as ATTACHMENT in its existing SQL union; MCP retains decision $userContent wrapping. See @haneinfo/attachments/agent-guide.md for authorization, storage, scanning, migration and retention. Apps adopting the optional package add its reverse instance relation; the core fragment does not depend on attachments.
|