@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/package.json +29 -4
- package/src/auth.ts +125 -0
- package/src/gate.ts +710 -0
- package/src/index.ts +24 -0
- package/src/mcp.ts +123 -0
- package/src/policy.ts +60 -0
- package/src/projections.ts +115 -0
- package/src/protocol.ts +51 -0
- package/src/queries.ts +148 -0
- package/src/registry.ts +235 -0
- package/src/state.ts +134 -0
- package/src/storage.ts +208 -0
- package/src/types.ts +121 -0
- package/README.md +0 -3
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