@sudoke/kernel 0.0.0-stage → 0.2.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/src/types.ts ADDED
@@ -0,0 +1,121 @@
1
+ import type { ZodType } from 'zod'
2
+
3
+ /** Role name — the app defines and registers its vocabulary (registerRoles). The kernel knows nothing about role semantics */
4
+ export type Role = string
5
+
6
+ /** Recovery action classification — the value of recovery.action in refusal responses. The common protocol explains each action's meaning */
7
+ export type RecoveryAction = 'refresh' | 'fix_input' | 'reauthenticate' | 'retry' | 'stop'
8
+
9
+ /** Next-step guidance after a refusal — the error-code definition provides the default action; the throw site only adds extras such as query */
10
+ export interface RecoveryHint {
11
+ action?: RecoveryAction
12
+ /** Query name (a registered query) to re-read when the action is refresh — e.g. 'portfolio' */
13
+ query?: string
14
+ }
15
+
16
+ /** Error-code definition — an entry of the registry (registerErrorCodes). The sentence (reason) may change; the code stays stable */
17
+ export interface ErrorCodeDefinition {
18
+ description: string
19
+ recovery: RecoveryAction
20
+ /** Whether refusals with this code are warnings that can be overridden with a force:true retry — a flag separate from the recovery action */
21
+ canForce?: boolean
22
+ }
23
+
24
+ /** Identity that passed gate stages 1-2 (a human or their agent) */
25
+ export interface Identity {
26
+ userId: string
27
+ name: string
28
+ role: Role
29
+ /** Accessible business-target scope — interpretation belongs to the app policy */
30
+ scopes: string[]
31
+ /** Acting subject (app/agent) name for delegated execution — filled for delegation tokens */
32
+ act?: string
33
+ /** Delegation info — present only for agent tokens. Permissions are delegator permissions ∩ scopes */
34
+ delegation?: {
35
+ id: string
36
+ name: string
37
+ scopes: string[]
38
+ }
39
+ }
40
+
41
+ export interface DomainEvent {
42
+ type: string
43
+ aggregate_type: string
44
+ aggregate_id: string
45
+ payload: Record<string, unknown>
46
+ }
47
+
48
+ /**
49
+ * Command definition (the form). One entry of the command catalog.
50
+ * REST/MCP/CLI/docs are derived from this definition.
51
+ * Every hook that may touch storage (transition.current·precondition·invariants·execute) is
52
+ * asynchronous — the storage port is async, so hooks await their reads; targetOf stays synchronous
53
+ * (pure input extraction, no storage).
54
+ */
55
+ export interface CommandDefinition<I = any, O = any> {
56
+ name: string
57
+ description: string
58
+ example?: string
59
+ /** Deprecation notice — exposed in the catalog so connecting agents learn the replacement */
60
+ deprecated?: string
61
+ allowedRoles: Role[]
62
+ /** Scope kind — 'none' skips scope checks; any other value is interpreted by the app policy */
63
+ scope: 'none' | (string & {})
64
+ /** Extracts the business-target id from the input — feeds the app policy scope check */
65
+ targetOf?: (input: I) => string | undefined
66
+ input: ZodType<I>
67
+ /** Output contract — the shape of result in a success response. The gate validates it before commit (violation = stage-8 refusal + rollback) */
68
+ output: ZodType<O>
69
+ /** Business error codes (registered in the domain registry) this command can raise — published in the catalog.
70
+ * Gate-common codes (schema, permissions, transitions — common to every command) are not listed here */
71
+ errors?: readonly string[]
72
+ /** State-transition declaration — enforced against the transition table (machine) registered in the kernel registry.
73
+ * Convention: if the input has a `to` (target status) field, only rules leading to that status are accepted
74
+ * (otherwise the first rule for this command from the current status applies) */
75
+ transition?: {
76
+ machine: string
77
+ command: string
78
+ current: (input: I) => Promise<{ id: string | null; status: string }>
79
+ }
80
+ precondition?: (input: I) => Promise<void>
81
+ invariants?: (input: I, identity: Identity) => Promise<void>
82
+ /** Pure by design: never mutate state directly, only return events. The kernel applies projections.
83
+ * result is checked against the output contract */
84
+ execute: (input: I, identity: Identity) => Promise<{ events: DomainEvent[]; result: O }>
85
+ }
86
+
87
+ /** Stage names of the 9-stage gate — a fixed, published contract. GateError derives stageName from the
88
+ * stage number through this table, so a wrong name at a throw site can never reach responses or audits. */
89
+ export const STAGE_NAMES: readonly string[] = [
90
+ 'registry', // 0
91
+ 'identify', // 1
92
+ 'delegation', // 2
93
+ 'policy', // 3
94
+ 'schema', // 4
95
+ 'precondition', // 5
96
+ 'invariant', // 6
97
+ 'transition', // 7
98
+ 'execute', // 8
99
+ ]
100
+
101
+ /** A refusal with a stage number and a reason. Recorded as an audit event.
102
+ * Attaching code adds a stable identifier and recovery guidance to responses and audits
103
+ * (machines act on it without parsing sentences). */
104
+ export class GateError extends Error {
105
+ code?: string
106
+ recovery?: RecoveryHint
107
+ stageName: string
108
+ constructor(
109
+ public stage: number,
110
+ /** @deprecated derived from the stage number — whenever the stage is in STAGE_NAMES this argument is
111
+ * ignored and the table value is published (I6 fixed contract); kept only as a fallback for unknown numbers */
112
+ stageName: string,
113
+ message: string,
114
+ meta?: { code?: string; recovery?: RecoveryHint },
115
+ ) {
116
+ super(message)
117
+ this.stageName = STAGE_NAMES[stage] ?? stageName
118
+ if (meta?.code !== undefined) this.code = meta.code
119
+ if (meta?.recovery !== undefined) this.recovery = meta.recovery
120
+ }
121
+ }
package/README.md DELETED
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.