arkgate 4.8.23 → 4.8.25
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/CHANGELOG.md +153 -0
- package/README.md +7 -5
- package/bin/ark-check-runtime.mjs +41 -91
- package/bin/ark-dashboard.mjs +56 -53
- package/bin/ark-layer-match.mjs +707 -121
- package/bin/ark-mcp-runtime.mjs +448 -169
- package/bin/ark-mcp.mjs +68 -4
- package/bin/ark-shared.mjs +42 -22
- package/bin/ark.mjs +65 -97
- package/bin/lib/adapter-contract-types.mjs +5 -0
- package/bin/lib/adapter-contract.mjs +15 -0
- package/bin/lib/adoption-stance.mjs +2 -2
- package/bin/lib/adr-path.mjs +3 -3
- package/bin/lib/agent-gates.mjs +0 -61
- package/bin/lib/agent-homes.mjs +12 -21
- package/bin/lib/agent-projection-command.mjs +9 -5
- package/bin/lib/ambient-state.mjs +9 -30
- package/bin/lib/analysis-engine.mjs +15 -11
- package/bin/lib/architecture-scan.mjs +61 -15
- package/bin/lib/ark-order-doctor.mjs +4 -29
- package/bin/lib/ark-order-facts.mjs +319 -17
- package/bin/lib/ark-order-sensors.mjs +28 -101
- package/bin/lib/ark-order-types.mjs +3 -2
- package/bin/lib/ark-run-doctor.mjs +17 -28
- package/bin/lib/ark-run-facts.mjs +461 -48
- package/bin/lib/ark-run-sensors.mjs +6 -4
- package/bin/lib/arkgate-pins.mjs +91 -0
- package/bin/lib/arkrule-file-hints.mjs +2 -47
- package/bin/lib/arkrules-contract.mjs +124 -133
- package/bin/lib/arkrules-sensors.mjs +55 -252
- package/bin/lib/check-args.mjs +85 -1
- package/bin/lib/ci-and-commands.mjs +24 -78
- package/bin/lib/ci-merge-boundary.mjs +1 -1
- package/bin/lib/class-source-scan.mjs +479 -0
- package/bin/lib/clone-detection.mjs +474 -0
- package/bin/lib/codex-home.mjs +5 -3
- package/bin/lib/config-contract-slices.mjs +739 -0
- package/bin/lib/config-contract.mjs +42 -607
- package/bin/lib/config-extras.mjs +16 -22
- package/bin/lib/config-warnings.mjs +32 -0
- package/bin/lib/contract-smells.mjs +33 -15
- package/bin/lib/core-ratchet.mjs +0 -2
- package/bin/lib/dashboard-cli.mjs +62 -0
- package/bin/lib/deep-module-coach.mjs +2 -4
- package/bin/lib/deploy-path.mjs +13 -38
- package/bin/lib/design-delta.mjs +1 -1
- package/bin/lib/design-smells.mjs +2 -2
- package/bin/lib/diagnostic-catalog.mjs +23 -9
- package/bin/lib/doctor-advisories.mjs +78 -8
- package/bin/lib/doctor-green-cite.mjs +1 -1
- package/bin/lib/doctor-human.mjs +1 -1
- package/bin/lib/doctor-next-actions.mjs +19 -4
- package/bin/lib/doctor-plan.mjs +9 -13
- package/bin/lib/duplication-io.mjs +572 -0
- package/bin/lib/effective-contract-load.mjs +282 -83
- package/bin/lib/enforcement-profiles.mjs +40 -4
- package/bin/lib/entry-points-io.mjs +424 -0
- package/bin/lib/extra-merge-teeth.mjs +36 -0
- package/bin/lib/field-install.mjs +38 -14
- package/bin/lib/first-run-help.mjs +10 -5
- package/bin/lib/flat-parent-importers.mjs +139 -0
- package/bin/lib/flat-parent-pilot.mjs +40 -100
- package/bin/lib/gate-files.mjs +58 -90
- package/bin/lib/git-change-scope.mjs +109 -0
- package/bin/lib/github-enforcement.mjs +166 -29
- package/bin/lib/golden-pattern.mjs +1 -1
- package/bin/lib/hook-templates.mjs +17 -15
- package/bin/lib/host-support-matrix.mjs +3 -1
- package/bin/lib/html-report-advisories.mjs +4 -0
- package/bin/lib/html-report-depth.mjs +2 -2
- package/bin/lib/html-report.mjs +2 -2
- package/bin/lib/import-graph-projection.mjs +112 -0
- package/bin/lib/import-resolve.mjs +13 -1
- package/bin/lib/improvement-compass-doctor.mjs +1 -24
- package/bin/lib/install-migrate.mjs +50 -73
- package/bin/lib/invariant-coverage-io.mjs +4 -3
- package/bin/lib/invariant-coverage.mjs +85 -11
- package/bin/lib/invariant-probe-cli.mjs +347 -0
- package/bin/lib/invariant-probe-io.mjs +165 -0
- package/bin/lib/invariant-probe-runner.mjs +268 -0
- package/bin/lib/invariant-probe-sites.mjs +174 -0
- package/bin/lib/invariant-probe-workspace.mjs +183 -0
- package/bin/lib/invariant-probe.mjs +461 -0
- package/bin/lib/invariant-tests-path.mjs +16 -22
- package/bin/lib/literal-path-drift.mjs +4 -2
- package/bin/lib/managed-upgrade.mjs +2 -8
- package/bin/lib/mcp-adoption.mjs +13 -6
- package/bin/lib/mcp-hook-payload.mjs +403 -63
- package/bin/lib/orphan-modules-io.mjs +458 -0
- package/bin/lib/orphan-modules.mjs +251 -0
- package/bin/lib/outside-importers.mjs +197 -0
- package/bin/lib/package-manager.mjs +60 -2
- package/bin/lib/parse-health.mjs +1 -1
- package/bin/lib/passthrough-commands.mjs +83 -0
- package/bin/lib/persistence-write-hint.mjs +106 -0
- package/bin/lib/pin-dependent-gates.mjs +117 -0
- package/bin/lib/policy-delta-io.mjs +219 -14
- package/bin/lib/post-green-path.mjs +1 -1
- package/bin/lib/prepare-change.mjs +115 -7
- package/bin/lib/prepare-write.mjs +2 -2
- package/bin/lib/presets.mjs +59 -73
- package/bin/lib/product-copy.mjs +1 -6
- package/bin/lib/project-root.mjs +31 -62
- package/bin/lib/remediation.mjs +23 -4
- package/bin/lib/resolved-candidate-facts.mjs +405 -117
- package/bin/lib/rules-inventory.mjs +22 -3
- package/bin/lib/rules-under-contract.mjs +247 -9
- package/bin/lib/scan-files.mjs +36 -4
- package/bin/lib/schema-validation.mjs +130 -0
- package/bin/lib/sensor-promote-cli.mjs +2 -11
- package/bin/lib/sensor-promote-io.mjs +33 -22
- package/bin/lib/sensor-promotion.mjs +1 -1
- package/bin/lib/skill-catalog-apply.mjs +1 -1
- package/bin/lib/skill-install.mjs +42 -38
- package/bin/lib/snippet-analysis.mjs +140 -6
- package/bin/lib/source-policy.mjs +34 -0
- package/bin/lib/start-install-recovery.mjs +72 -2
- package/bin/lib/start-preview.mjs +31 -1
- package/bin/lib/states-transitions-presence.mjs +3 -3
- package/bin/lib/status-command.mjs +35 -22
- package/bin/lib/status-manifest.mjs +50 -30
- package/bin/lib/status-transition-catalog.mjs +0 -6
- package/bin/lib/suggestions.mjs +3 -3
- package/bin/lib/team-parliament-io.mjs +76 -88
- package/bin/lib/team-parliament.mjs +21 -10
- package/bin/lib/upgrade-behavior-changes.mjs +2 -2
- package/bin/lib/upgrade-command.mjs +2 -24
- package/bin/lib/upgrade-outcome.mjs +1 -1
- package/bin/lib/upstream-report.mjs +21 -10
- package/bin/lib/violations.mjs +10 -9
- package/bin/lib/weakest-link.mjs +13 -0
- package/bin/lib/write-path-capabilities.mjs +6 -4
- package/dist/chunk-A5EIY3HI.cjs +5 -0
- package/dist/chunk-AHACEKSV.js +16 -0
- package/dist/chunk-SVSQVGFJ.js +5 -0
- package/dist/chunk-UN5EH4QV.cjs +16 -0
- package/dist/{configTypes-Bbf_MFGe.d.ts → configTypes-GPvvdleM.d.cts} +30 -4
- package/dist/configTypes-GPvvdleM.d.ts +257 -0
- package/dist/eslint/index.cjs +18 -5
- package/dist/eslint/index.d.cts +368 -0
- package/dist/eslint/index.d.ts +139 -156
- package/dist/eslint/index.js +11 -5
- package/dist/index.cjs +36 -35
- package/dist/index.d.cts +5547 -0
- package/dist/index.d.ts +3283 -198
- package/dist/index.js +36 -35
- package/dist/inspectorListen-6DQVJ4DC.js +1 -0
- package/dist/inspectorListen-KGMIQ2TF.cjs +1 -0
- package/dist/nestjs/index.cjs +1 -18
- package/dist/nestjs/index.d.cts +22 -0
- package/dist/nestjs/index.d.ts +1 -3
- package/dist/nestjs/index.js +1 -18
- package/dist/order/index.cjs +1 -1
- package/dist/order/index.d.cts +155 -0
- package/dist/order/index.d.ts +15 -3
- package/dist/order/index.js +1 -1
- package/dist/runtime/index.cjs +13 -30
- package/dist/{diagnosticCatalog-35mrwAHe.d.ts → runtime/index.d.cts} +828 -276
- package/dist/runtime/index.d.ts +2741 -133
- package/dist/runtime/index.js +13 -30
- package/dist/{types-Bdj32QwA.d.ts → types-CnauMQQL.d.cts} +607 -163
- package/dist/types-CnauMQQL.d.ts +1800 -0
- package/docs/README.md +3 -1
- package/docs/agent-guide.md +217 -16
- package/docs/ai-gates.md +174 -26
- package/docs/arkorder.md +32 -15
- package/docs/brownfield-adoption.md +5 -1
- package/docs/configuration.md +230 -31
- package/docs/develop.md +2 -1
- package/docs/diagnostics.md +212 -19
- package/docs/package-surface.md +35 -9
- package/docs/product-voice.md +7 -1
- package/package.json +69 -19
- package/schemas/ark.analysis-result.schema.json +15 -0
- package/schemas/ark.config.schema.json +77 -12
- package/schemas/ark.invariant-probe.schema.json +368 -0
- package/schemas/ark.resolved-candidate-facts.schema.json +1 -1
- package/schemas/ark.status-manifest.schema.json +22 -0
- package/server.json +3 -9
- package/templates/agent-skills/README.md +1 -1
- package/templates/agent-skills/ark-adopt/SKILL.md +5 -1
- package/templates/agent-skills/ark-contract/SKILL.md +17 -0
- package/templates/agent-skills/ark-coverage/SKILL.md +2 -0
- package/templates/agent-skills/ark-explore/SKILL.md +7 -0
- package/templates/agent-skills/ark-fix/SKILL.md +20 -0
- package/templates/agent-skills/ark-order/SKILL.md +4 -2
- package/templates/agent-skills/ark-place/SKILL.md +8 -0
- package/templates/agent-skills/ark-runtime/SKILL.md +6 -1
- package/templates/arkrules/PersistenceAdapters.json +1 -1
- package/templates/arkrules/PresentationAdapters.json +1 -1
- package/templates/skills/ark-adopt.md +5 -1
- package/templates/skills/ark-contract.md +17 -0
- package/templates/skills/ark-coverage.md +2 -0
- package/templates/skills/ark-explore.md +7 -0
- package/templates/skills/ark-fix.md +20 -0
- package/templates/skills/ark-order.md +4 -2
- package/templates/skills/ark-place.md +8 -0
- package/templates/skills/ark-runtime.md +6 -1
- package/bin/lib/ark-order-error.mjs +0 -18
- package/bin/lib/ark-order-invariants.mjs +0 -346
- package/dist/types-Ik_OakcI.d.ts +0 -183
|
@@ -1,128 +1,366 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
type MaybePromise<T> = T | Promise<T>;
|
|
2
|
+
type AuditRecordType = 'event.published' | 'event.rawPublish' | 'event.handoffFailed' | 'event.intercepted' | 'interceptor.error' | 'policy.softViolation' | 'policy.hardViolation' | 'layer.observedViolation' | 'layer.observedFlowUnresolvable' | 'handler.error' | 'hook.error' | 'workflow.started' | 'workflow.step.completed' | 'workflow.step.failed' | 'workflow.compensation.completed' | 'workflow.completed' | 'workflow.failed' | 'projection.applied' | 'metadata.changed';
|
|
3
|
+
interface AuditRecord {
|
|
4
|
+
id: string;
|
|
5
|
+
type: AuditRecordType;
|
|
6
|
+
timestamp: string;
|
|
7
|
+
source?: string;
|
|
8
|
+
actor?: string;
|
|
9
|
+
intent?: string;
|
|
10
|
+
correlationId?: string;
|
|
11
|
+
causationId?: string;
|
|
12
|
+
subject?: string;
|
|
13
|
+
details?: unknown;
|
|
14
|
+
}
|
|
15
|
+
interface AuditRecordInput {
|
|
16
|
+
type: AuditRecordType;
|
|
17
|
+
timestamp?: string;
|
|
18
|
+
source?: string;
|
|
19
|
+
actor?: string;
|
|
20
|
+
intent?: string;
|
|
21
|
+
correlationId?: string;
|
|
22
|
+
causationId?: string;
|
|
23
|
+
subject?: string;
|
|
24
|
+
details?: unknown;
|
|
25
|
+
}
|
|
26
|
+
interface AuditQuery {
|
|
27
|
+
type?: AuditRecordType;
|
|
28
|
+
intent?: string;
|
|
29
|
+
correlationId?: string;
|
|
30
|
+
subject?: string;
|
|
31
|
+
since?: string;
|
|
32
|
+
until?: string;
|
|
33
|
+
limit?: number;
|
|
34
|
+
}
|
|
3
35
|
/**
|
|
4
|
-
*
|
|
36
|
+
* Pluggable persistence for audit records.
|
|
5
37
|
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
* -
|
|
9
|
-
* - Soft policies: violations are reported as warnings but do not throw.
|
|
38
|
+
* **Durability stance (R9):** Default is `InMemoryAuditStore` — reference only, not
|
|
39
|
+
* production durability (lost on restart). Implement this interface for durable audit.
|
|
40
|
+
* See `docs/production-hardening.md`.
|
|
10
41
|
*/
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
hardViolations: PolicyViolation[];
|
|
16
|
-
softViolations: PolicyViolation[];
|
|
42
|
+
interface AuditStore {
|
|
43
|
+
append(record: AuditRecord): MaybePromise<void>;
|
|
44
|
+
query(query?: AuditQuery): MaybePromise<AuditRecord[]>;
|
|
45
|
+
clear(): MaybePromise<void>;
|
|
17
46
|
}
|
|
18
47
|
/**
|
|
19
|
-
*
|
|
20
|
-
*
|
|
48
|
+
* High-level audit API used by the event bus / kernel.
|
|
49
|
+
* Durability is that of the injected `AuditStore` (default in-memory).
|
|
21
50
|
*/
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
51
|
+
interface AuditTrail {
|
|
52
|
+
record(input: AuditRecordInput): Promise<AuditRecord>;
|
|
53
|
+
query(query?: AuditQuery): Promise<AuditRecord[]>;
|
|
54
|
+
clear(): Promise<void>;
|
|
55
|
+
}
|
|
56
|
+
interface CreateAuditTrailOptions {
|
|
57
|
+
/** Durable store when provided; otherwise `InMemoryAuditStore` (not production durability). */
|
|
58
|
+
store?: AuditStore;
|
|
59
|
+
maxRecords?: number;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Type vocabulary for the ark.config.json contract (U02 pilot 1).
|
|
64
|
+
*
|
|
65
|
+
* Pure declarations only — no runtime values. The loader/validator logic and the
|
|
66
|
+
* published JSON Schema live in ./configContract.ts. Extra defaulting lives in
|
|
67
|
+
* ./configExtras.ts (generated sibling `config-extras.mjs`). Type-only imports
|
|
68
|
+
* from this file are erased on transpile.
|
|
69
|
+
*/
|
|
70
|
+
type ArkConfigSchemaVersion = '1.0' | '1.1' | '1.2' | '1.3';
|
|
71
|
+
type ArkConfigCyclePolicy = 'strict' | 'soft' | 'framework-soft' | 'off';
|
|
72
|
+
type ArkConfigLayerCapabilities = {
|
|
73
|
+
deny?: string[];
|
|
74
|
+
};
|
|
75
|
+
/** Who this folder is for. Metadata — not import-rule teeth. Absence is silent. */
|
|
76
|
+
type ArkConfigLayerTrustBoundary = 'public' | 'auth' | 'admin' | 'internal';
|
|
77
|
+
type ArkConfigLayer = {
|
|
78
|
+
name: string;
|
|
79
|
+
patterns: string[];
|
|
80
|
+
exclude?: string[];
|
|
81
|
+
intentPrefixes?: string[];
|
|
25
82
|
/**
|
|
26
|
-
*
|
|
83
|
+
* App-context caption for this layer.
|
|
84
|
+
* Metadata — excluded from policy hash. Absence is silent.
|
|
27
85
|
*/
|
|
28
|
-
|
|
86
|
+
description?: string;
|
|
29
87
|
/**
|
|
30
|
-
*
|
|
88
|
+
* Who this folder is for: public | auth | admin | internal.
|
|
89
|
+
* Metadata — excluded from policy hash. Absence is silent. Not host/CI TLS.
|
|
31
90
|
*/
|
|
32
|
-
|
|
91
|
+
trustBoundary?: ArkConfigLayerTrustBoundary;
|
|
33
92
|
/**
|
|
34
|
-
*
|
|
93
|
+
* Who owns this house: GitHub handles or emails (same identity as stewards).
|
|
94
|
+
* Metadata — excluded from policy hash. Absence is silent unless
|
|
95
|
+
* `requireLayerOwners` is true. Not import-rule teeth.
|
|
35
96
|
*/
|
|
36
|
-
|
|
97
|
+
owners?: string[];
|
|
98
|
+
forbiddenGlobals?: string[];
|
|
99
|
+
/** ADR 0009 D2 — opt-in effect-capability walls; absence changes no verdict. */
|
|
100
|
+
capabilities?: ArkConfigLayerCapabilities;
|
|
101
|
+
/** Dual-depth sugar: `pure: true` denies all seven capabilities. */
|
|
102
|
+
pure?: boolean;
|
|
103
|
+
mayImportInfrastructure?: boolean;
|
|
104
|
+
optional?: boolean;
|
|
37
105
|
/**
|
|
38
|
-
*
|
|
39
|
-
*
|
|
40
|
-
* - Soft violations are collected and can be observed (returned or logged).
|
|
41
|
-
* - Hard violations cause an error to be thrown (by default).
|
|
42
|
-
*
|
|
43
|
-
* @returns Evaluation result (including any soft violations)
|
|
44
|
-
* @throws Error if any hard policy is violated
|
|
106
|
+
* Future house: empty globs are expected. `--strict-config` must not fail.
|
|
107
|
+
* Typo warning (`CONFIG_LAYER_PATTERN_NO_MATCHES`) is skipped.
|
|
45
108
|
*/
|
|
46
|
-
|
|
109
|
+
reserved?: boolean;
|
|
110
|
+
/** Alias of reserved — empty pattern matches are allowed. */
|
|
111
|
+
allowEmpty?: boolean;
|
|
112
|
+
};
|
|
113
|
+
/** How a starred `sliceFolders` prefix is named. Absent equals `path`. */
|
|
114
|
+
type ArkConfigSliceIdentity = 'path' | 'stars';
|
|
115
|
+
type ArkConfigRule = {
|
|
116
|
+
from: string;
|
|
117
|
+
to: string;
|
|
118
|
+
allowed: boolean;
|
|
119
|
+
message?: string;
|
|
120
|
+
peerIsolation?: boolean;
|
|
121
|
+
sliceFolders?: string[];
|
|
47
122
|
/**
|
|
48
|
-
*
|
|
123
|
+
* How a starred `sliceFolders` prefix is named.
|
|
124
|
+
* Absent and `path` keep today's ids. `stars` is the last literal plus every
|
|
125
|
+
* star binding (a star before the last literal is kept too).
|
|
49
126
|
*/
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
/**
|
|
54
|
-
|
|
55
|
-
*
|
|
56
|
-
* Central registry for semantic intents.
|
|
57
|
-
* Supports registration, duplicate prevention, and declared dependency relationships.
|
|
58
|
-
*
|
|
59
|
-
* This is a core building block for governance, dependency graphs, and policy enforcement.
|
|
60
|
-
*/
|
|
61
|
-
|
|
62
|
-
/**
|
|
63
|
-
* Options for declaring relationships when defining an intent.
|
|
64
|
-
*/
|
|
65
|
-
interface DefineIntentOptions {
|
|
66
|
-
/** Other intents this one depends on (semantic names) */
|
|
67
|
-
dependsOn?: IntentName[];
|
|
68
|
-
/** Intents that this one produces / triggers */
|
|
69
|
-
produces?: IntentName[];
|
|
70
|
-
}
|
|
71
|
-
/**
|
|
72
|
-
* IntentRegistry manages all registered intents and their declared relationships.
|
|
73
|
-
*/
|
|
74
|
-
declare class IntentRegistry {
|
|
75
|
-
private readonly intents;
|
|
76
|
-
private readonly dependencies;
|
|
77
|
-
private readonly productions;
|
|
127
|
+
sliceIdentity?: ArkConfigSliceIdentity;
|
|
128
|
+
/** Roots the repo declares shared on purpose — evidence, not unclassifiable. */
|
|
129
|
+
sharedRoots?: string[];
|
|
130
|
+
/** Directed slice→slice edges the repo declares on purpose. */
|
|
131
|
+
allowedCrossSlice?: ArkConfigCrossSliceEdge[];
|
|
78
132
|
/**
|
|
79
|
-
*
|
|
80
|
-
*
|
|
81
|
-
*
|
|
82
|
-
*
|
|
83
|
-
*
|
|
133
|
+
* `"deny"` blocks a shared root from importing a slice.
|
|
134
|
+
* `"deny-cross-parent"` leaves that hop allowed and asks the whole-graph
|
|
135
|
+
* check to report a slice that reaches another universe through shared.
|
|
136
|
+
* The object form carries `stopAt`: composition roots the walk never
|
|
137
|
+
* passes through.
|
|
84
138
|
*/
|
|
85
|
-
|
|
139
|
+
sharedImportsSlice?: ArkConfigSharedImportsSlice;
|
|
86
140
|
/**
|
|
87
|
-
*
|
|
88
|
-
*
|
|
89
|
-
*
|
|
90
|
-
* @param from - The source intent (e.g. an Application operation)
|
|
91
|
-
* @param to - The target intent it depends on (e.g. a Domain event or concept)
|
|
141
|
+
* Optional inner wall. Absent keeps today's universe-wall output.
|
|
142
|
+
* `siblings` defaults to deny. An object keeps that default and lists enforced subtrees.
|
|
143
|
+
* `parentMayImportChild` defaults to false.
|
|
92
144
|
*/
|
|
93
|
-
|
|
145
|
+
childSlices?: ArkConfigChildSlices;
|
|
146
|
+
};
|
|
147
|
+
type ArkConfigSharedImportsSlice = 'deny' | 'deny-cross-parent' | {
|
|
148
|
+
mode: 'deny-cross-parent';
|
|
149
|
+
stopAt: string[];
|
|
150
|
+
};
|
|
151
|
+
type ArkConfigChildSlices = {
|
|
152
|
+
sliceFolders: string[];
|
|
153
|
+
sliceIdentity?: ArkConfigSliceIdentity;
|
|
154
|
+
commonFolders?: string[];
|
|
94
155
|
/**
|
|
95
|
-
*
|
|
156
|
+
* `ratchet` on the object form: absent turns the anti-growth ratchet on only
|
|
157
|
+
* when the baseline already records an advisory crossing of this rule;
|
|
158
|
+
* `true` always; `false` measures only.
|
|
96
159
|
*/
|
|
97
|
-
|
|
160
|
+
siblings?: 'deny' | 'advisory' | {
|
|
161
|
+
default: 'deny' | 'advisory';
|
|
162
|
+
enforce?: string[];
|
|
163
|
+
ratchet?: boolean;
|
|
164
|
+
};
|
|
165
|
+
parentMayImportChild?: boolean;
|
|
166
|
+
/** Text for inner-wall findings (sibling, common → child). Absent: ArkGate default, never the rule message. */
|
|
167
|
+
message?: string;
|
|
98
168
|
/**
|
|
99
|
-
*
|
|
169
|
+
* Directed child-slice allowances. `*` is one whole path segment.
|
|
170
|
+
* Clears a sibling crossing only. The universe `allowedCrossSlice` does not read this list.
|
|
100
171
|
*/
|
|
101
|
-
|
|
172
|
+
allowedCrossSlice?: ArkConfigCrossSliceEdge[];
|
|
102
173
|
/**
|
|
103
|
-
*
|
|
174
|
+
* Files outside the slice trees, borrowed onto a child id until they move.
|
|
175
|
+
* `to` is the universe id plus one child segment.
|
|
104
176
|
*/
|
|
105
|
-
|
|
177
|
+
sliceAliases?: ArkConfigSliceAlias[];
|
|
106
178
|
/**
|
|
107
|
-
*
|
|
179
|
+
* Filename at each child slice root. `<Layer>` is the only token.
|
|
180
|
+
* Example: `arkrules.<Layer>.json`.
|
|
108
181
|
*/
|
|
109
|
-
|
|
182
|
+
arkRulesFile?: string;
|
|
183
|
+
};
|
|
184
|
+
type ArkConfigSliceAlias = {
|
|
185
|
+
from: string;
|
|
186
|
+
to: string;
|
|
187
|
+
/** True: the path stays. It is not an owed move and does not clear other honesty debt. */
|
|
188
|
+
pinned?: boolean;
|
|
189
|
+
/** Doctor label, such as `framework-route`. A label alone does not pin. */
|
|
190
|
+
reason?: string;
|
|
191
|
+
};
|
|
192
|
+
type ArkConfigCrossSliceEdge = {
|
|
193
|
+
from: string;
|
|
194
|
+
to: string;
|
|
195
|
+
};
|
|
196
|
+
type ArkConfigSafety = {
|
|
197
|
+
maxTsSuppressions?: number;
|
|
198
|
+
maxAnyCasts?: number;
|
|
199
|
+
allowInMemory?: boolean;
|
|
200
|
+
allowDisabledPeerIsolation?: boolean;
|
|
201
|
+
};
|
|
202
|
+
/**
|
|
203
|
+
* Optional invariant-coverage scan controls. Absence keeps the built-in
|
|
204
|
+
* defaults (test-name heuristic, 400-file budget) and changes no verdict.
|
|
205
|
+
*/
|
|
206
|
+
type ArkConfigCoverage = {
|
|
207
|
+
/** Globs that decide which files count as tests (replaces the name heuristic). */
|
|
208
|
+
testGlobs?: string[];
|
|
209
|
+
/** Max files loaded as coverage evidence before the budget is exhausted. */
|
|
210
|
+
maxFiles?: number;
|
|
110
211
|
/**
|
|
111
|
-
*
|
|
212
|
+
* Path prefixes where this project declares its test runner actually executes
|
|
213
|
+
* tests. ArkGate never runs anything: this is a second declaration to compare
|
|
214
|
+
* the coverage scan against, so a covering test found outside them is reported
|
|
215
|
+
* (INVARIANT_COVERAGE_OUTSIDE_ROOTS) instead of silently certifying the
|
|
216
|
+
* invariant. Absence is silent unless any catalogued invariant is enforced —
|
|
217
|
+
* then missing roots fail closed (INVARIANT_COVERAGE_ROOTS_MISSING).
|
|
112
218
|
*/
|
|
113
|
-
|
|
219
|
+
coverageRoots?: string[];
|
|
220
|
+
};
|
|
221
|
+
/**
|
|
222
|
+
* ADR 0012 — optional map of layer name → project-relative ArkRules file path.
|
|
223
|
+
* Absence changes no inter-layer verdict.
|
|
224
|
+
*/
|
|
225
|
+
/** One path, or several paths merged into that layer's catalog. */
|
|
226
|
+
type ArkConfigArkRulesRef = string | string[];
|
|
227
|
+
type ArkConfigArkRulesRefs = Record<string, ArkConfigArkRulesRef>;
|
|
228
|
+
/** ADR 0020 — advisory never adds merge teeth; enforced is the extra's merge plane. */
|
|
229
|
+
type ArkConfigArkRunMode = 'advisory' | 'enforced';
|
|
230
|
+
/**
|
|
231
|
+
* ADR 0020 — optional inline ArkRun extra (schema 1.2+). Absence is silent.
|
|
232
|
+
* Present objects are fully defaulted by the loader.
|
|
233
|
+
*/
|
|
234
|
+
type ArkConfigArkRun = {
|
|
235
|
+
mode: ArkConfigArkRunMode;
|
|
236
|
+
compositionRoots: string[];
|
|
237
|
+
kernelRoots?: string[];
|
|
238
|
+
managedLayers: string[];
|
|
239
|
+
requireDeclarations: boolean;
|
|
240
|
+
ignoreDirectNewForErrors?: boolean;
|
|
241
|
+
};
|
|
242
|
+
/** ADR 0027 — advisory never adds merge teeth; enforced is the extra's merge plane. */
|
|
243
|
+
type ArkConfigArkOrderMode = 'advisory' | 'enforced';
|
|
244
|
+
/**
|
|
245
|
+
* ADR 0027 — optional inline ArkOrder extra (schema 1.3+). Absence is silent.
|
|
246
|
+
* Present objects are fully defaulted by the loader.
|
|
247
|
+
*/
|
|
248
|
+
type ArkConfigArkOrder = {
|
|
249
|
+
mode: ArkConfigArkOrderMode;
|
|
250
|
+
planeRoots: string[];
|
|
251
|
+
managedLayers: string[];
|
|
114
252
|
/**
|
|
115
|
-
*
|
|
253
|
+
* Haken cap on one `release()` / `assertXiKeyCap` (default 7).
|
|
254
|
+
* Not a cap on the `xiKeys` watchlist length.
|
|
116
255
|
*/
|
|
117
|
-
|
|
256
|
+
maxXiKeys: number;
|
|
118
257
|
/**
|
|
119
|
-
*
|
|
258
|
+
* Slow product keys the team can already name (plan, cost code, protocol).
|
|
259
|
+
* Optional. Empty → `ARKORDER_XI_FIELD_WRITE` stays silent.
|
|
260
|
+
* Repo-wide watchlist — not compared to `maxXiKeys`.
|
|
120
261
|
*/
|
|
121
|
-
|
|
262
|
+
xiKeys: string[];
|
|
122
263
|
/**
|
|
123
|
-
*
|
|
264
|
+
* Optional globs that narrow ξ field-write observation inside `managedLayers`.
|
|
265
|
+
* Same glob engine as `layers[].patterns`. Absence or empty → every file in
|
|
266
|
+
* those layers. Non-empty → emit only when the layer is managed AND the file
|
|
267
|
+
* matches at least one glob.
|
|
124
268
|
*/
|
|
125
|
-
|
|
269
|
+
appliesTo?: string[];
|
|
270
|
+
};
|
|
271
|
+
type ArkConfig = {
|
|
272
|
+
$schema: string;
|
|
273
|
+
schemaVersion: ArkConfigSchemaVersion;
|
|
274
|
+
name?: string;
|
|
275
|
+
include: string[];
|
|
276
|
+
exclude?: string[];
|
|
277
|
+
excludeGenerated?: boolean;
|
|
278
|
+
frameworkOverlay?: string;
|
|
279
|
+
layers: ArkConfigLayer[];
|
|
280
|
+
rules: ArkConfigRule[];
|
|
281
|
+
cyclePolicy?: ArkConfigCyclePolicy;
|
|
282
|
+
dynamicImportAllowlist?: string[];
|
|
283
|
+
safety?: ArkConfigSafety;
|
|
284
|
+
/**
|
|
285
|
+
* Invariant-coverage scan controls (test globs + file budget).
|
|
286
|
+
* Absence keeps the defaults; it never turns coverage on by itself.
|
|
287
|
+
*/
|
|
288
|
+
coverage?: ArkConfigCoverage;
|
|
289
|
+
/** ADR 0012 — modular ArkRules references (schema 1.1+). */
|
|
290
|
+
arkRules?: ArkConfigArkRulesRefs;
|
|
291
|
+
/** ADR 0020 — optional ArkRun extra (schema 1.2+). Absence changes no Layers/ArkRules verdict. */
|
|
292
|
+
arkRun?: ArkConfigArkRun;
|
|
293
|
+
/** ADR 0027 — optional ArkOrder extra (schema 1.3+). Absence changes no Layers/ArkRules/ArkRun verdict. */
|
|
294
|
+
arkOrder?: ArkConfigArkOrder;
|
|
295
|
+
/**
|
|
296
|
+
* Optional GitHub handles or emails who may loosen the contract or grow the baseline.
|
|
297
|
+
* Metadata — excluded from policy hash. Absence means no steward lock (policy-ack still applies).
|
|
298
|
+
*/
|
|
299
|
+
stewards?: string[];
|
|
300
|
+
/**
|
|
301
|
+
* When true, every non-reserved layer must name `owners`. Absence/false is
|
|
302
|
+
* silent. This flag is policy teeth (stays in policyHash). Owners themselves
|
|
303
|
+
* stay metadata.
|
|
304
|
+
*/
|
|
305
|
+
requireLayerOwners?: boolean;
|
|
306
|
+
};
|
|
307
|
+
/** Original input version when the loader rewrote schemaVersion toward current. */
|
|
308
|
+
type ArkConfigMigratedFrom = 'unversioned' | '1.0' | '1.1' | '1.2' | null;
|
|
309
|
+
type ArkConfigLoadResult = {
|
|
310
|
+
config: ArkConfig;
|
|
311
|
+
migratedFrom: ArkConfigMigratedFrom;
|
|
312
|
+
};
|
|
313
|
+
|
|
314
|
+
/**
|
|
315
|
+
* Architecture layer profiles.
|
|
316
|
+
*
|
|
317
|
+
* A profile turns semantic names such as `Domain.Order.Placed` into governed
|
|
318
|
+
* layer names and dependency rules.
|
|
319
|
+
*/
|
|
320
|
+
|
|
321
|
+
interface ArchitectureLayer {
|
|
322
|
+
name: string;
|
|
323
|
+
prefixes: string[];
|
|
324
|
+
/**
|
|
325
|
+
* Custom matcher for teams whose intent names don't follow prefix conventions.
|
|
326
|
+
* Checked before any prefix matching, in layer declaration order. A layer may
|
|
327
|
+
* use `match` alone (with `prefixes: []`), prefixes alone, or both.
|
|
328
|
+
*/
|
|
329
|
+
match?: (name: string) => boolean;
|
|
330
|
+
description?: string;
|
|
331
|
+
trustBoundary?: 'public' | 'auth' | 'admin' | 'internal';
|
|
332
|
+
owners?: string[];
|
|
333
|
+
order?: number;
|
|
334
|
+
}
|
|
335
|
+
type ArchitectureRule = ArkConfigRule;
|
|
336
|
+
interface ArchitectureProfile {
|
|
337
|
+
name: string;
|
|
338
|
+
layers: ArchitectureLayer[];
|
|
339
|
+
rules: ArchitectureRule[];
|
|
340
|
+
resolveLayer(name: string): string | undefined;
|
|
341
|
+
}
|
|
342
|
+
interface CreateArchitectureProfileOptions {
|
|
343
|
+
name: string;
|
|
344
|
+
layers: ArchitectureLayer[];
|
|
345
|
+
rules?: ArchitectureRule[];
|
|
346
|
+
}
|
|
347
|
+
interface CreateArchitectureProfileFromArkConfigOptions {
|
|
348
|
+
/** Runtime profile name. Default: config.name or "ark.config.json". */
|
|
349
|
+
name?: string;
|
|
350
|
+
}
|
|
351
|
+
type ArchitectureLayerConfig = ArkConfigLayer;
|
|
352
|
+
type ArkCheckConfig = Omit<ArkConfig, '$schema' | 'schemaVersion' | 'rules'> & {
|
|
353
|
+
$schema?: string;
|
|
354
|
+
schemaVersion?: ArkConfig['schemaVersion'];
|
|
355
|
+
rules?: ArchitectureRule[];
|
|
356
|
+
};
|
|
357
|
+
interface CreateElevenLayerArkConfigOptions {
|
|
358
|
+
/** Source root used in generated file patterns. Default: "src". */
|
|
359
|
+
rootDir?: string;
|
|
360
|
+
/** Include entries for ark-check. Default: [rootDir]. */
|
|
361
|
+
include?: string[];
|
|
362
|
+
/** Mark generated layers optional. Default: true. */
|
|
363
|
+
optionalLayers?: boolean;
|
|
126
364
|
}
|
|
127
365
|
|
|
128
366
|
/**
|
|
@@ -180,65 +418,161 @@ interface DependencyGraph {
|
|
|
180
418
|
detectViolations(rules?: Array<(edges: GraphEdge[]) => string[]>): string[];
|
|
181
419
|
}
|
|
182
420
|
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
421
|
+
/**
|
|
422
|
+
* Core domain primitives for Ark.
|
|
423
|
+
* These types are the foundation for all governance concepts.
|
|
424
|
+
*/
|
|
425
|
+
/**
|
|
426
|
+
* Semantic intent names follow a convention:
|
|
427
|
+
* - Domain.* for domain events and entities
|
|
428
|
+
* - Application.* for use-cases / orchestration
|
|
429
|
+
* - Adapter.* for integration points
|
|
430
|
+
* - Workflow.* for sagas and processes
|
|
431
|
+
* - Job.* for background jobs and scheduling
|
|
432
|
+
* - Presentation.* for UI/API adapters
|
|
433
|
+
* - Reporting.* for read models and projections
|
|
434
|
+
* - Metadata.* for extensibility contracts
|
|
435
|
+
* - Security.* / Audit.* / Observability.* for cross-cutting kernel concerns
|
|
436
|
+
* - Kernel.* for Ark-owned governance signals
|
|
437
|
+
*/
|
|
438
|
+
type IntentName = `Domain.${string}` | `Application.${string}` | `Adapter.${string}` | `Workflow.${string}` | `Job.${string}` | `Presentation.${string}` | `Reporting.${string}` | `Metadata.${string}` | `Security.${string}` | `Audit.${string}` | `Observability.${string}` | `Kernel.${string}`;
|
|
439
|
+
type CorrelationId = string;
|
|
440
|
+
interface EventMetadata {
|
|
441
|
+
occurredAt: string;
|
|
442
|
+
source: string;
|
|
443
|
+
kernelInstanceId?: string;
|
|
444
|
+
eventVersion?: string;
|
|
445
|
+
schemaVersion?: string;
|
|
446
|
+
allowInterception?: boolean;
|
|
447
|
+
interceptions?: Array<{
|
|
448
|
+
interceptorId: string;
|
|
449
|
+
timestamp: string;
|
|
450
|
+
}>;
|
|
451
|
+
correlationId?: CorrelationId;
|
|
204
452
|
causationId?: string;
|
|
205
|
-
|
|
206
|
-
|
|
453
|
+
traceId?: string;
|
|
454
|
+
spanId?: string;
|
|
455
|
+
parentSpanId?: string;
|
|
456
|
+
[key: string]: unknown;
|
|
207
457
|
}
|
|
208
|
-
interface
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
subject?: string;
|
|
213
|
-
since?: string;
|
|
214
|
-
until?: string;
|
|
215
|
-
limit?: number;
|
|
458
|
+
interface DomainEvent<Name extends IntentName = IntentName, Payload = unknown> {
|
|
459
|
+
intent: Name;
|
|
460
|
+
payload: Payload;
|
|
461
|
+
metadata: EventMetadata;
|
|
216
462
|
}
|
|
463
|
+
|
|
217
464
|
/**
|
|
218
|
-
*
|
|
465
|
+
* Intent-specific types for the Ark kernel.
|
|
219
466
|
*
|
|
220
|
-
*
|
|
221
|
-
*
|
|
222
|
-
* See `docs/production-hardening.md`.
|
|
467
|
+
* Intents provide semantic naming for every important concept in the system
|
|
468
|
+
* (domain events, application operations, adapters, workflows).
|
|
223
469
|
*/
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
470
|
+
|
|
471
|
+
/**
|
|
472
|
+
* An IntentCreator is a callable that creates a strongly-typed DomainEvent
|
|
473
|
+
* when invoked with a payload.
|
|
474
|
+
*
|
|
475
|
+
* It also carries the semantic `name`.
|
|
476
|
+
*
|
|
477
|
+
* @example
|
|
478
|
+
* const OrderPlaced = defineIntent<'Domain.Order.OrderPlaced', { orderId: string }>('Domain.Order.OrderPlaced');
|
|
479
|
+
* const event = OrderPlaced({ orderId: 'o-1' });
|
|
480
|
+
*/
|
|
481
|
+
interface IntentCreator<Name extends IntentName, Payload = unknown> {
|
|
482
|
+
/**
|
|
483
|
+
* Creates a DomainEvent for this intent.
|
|
484
|
+
*/
|
|
485
|
+
(payload: Payload): DomainEvent<Name, Payload>;
|
|
486
|
+
/**
|
|
487
|
+
* The fully-qualified semantic name of the intent (e.g. "Domain.Order.OrderPlaced").
|
|
488
|
+
*/
|
|
489
|
+
readonly name: Name;
|
|
228
490
|
}
|
|
491
|
+
/** Kind of relationship between two intents. */
|
|
492
|
+
type IntentRelationshipKind = 'dependsOn' | 'produces';
|
|
229
493
|
/**
|
|
230
|
-
*
|
|
231
|
-
*
|
|
494
|
+
* Relationship declarations between intents.
|
|
495
|
+
* Used for dependency analysis and graph generation.
|
|
232
496
|
*/
|
|
233
|
-
interface
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
497
|
+
interface IntentRelationship {
|
|
498
|
+
from: string;
|
|
499
|
+
to: string;
|
|
500
|
+
kind: IntentRelationshipKind;
|
|
237
501
|
}
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
502
|
+
|
|
503
|
+
/**
|
|
504
|
+
* IntentRegistry
|
|
505
|
+
*
|
|
506
|
+
* Central registry for semantic intents.
|
|
507
|
+
* Supports registration, duplicate prevention, and declared dependency relationships.
|
|
508
|
+
*
|
|
509
|
+
* This is a core building block for governance, dependency graphs, and policy enforcement.
|
|
510
|
+
*/
|
|
511
|
+
|
|
512
|
+
/**
|
|
513
|
+
* Options for declaring relationships when defining an intent.
|
|
514
|
+
*/
|
|
515
|
+
interface DefineIntentOptions {
|
|
516
|
+
/** Other intents this one depends on (semantic names) */
|
|
517
|
+
dependsOn?: IntentName[];
|
|
518
|
+
/** Intents that this one produces / triggers */
|
|
519
|
+
produces?: IntentName[];
|
|
520
|
+
}
|
|
521
|
+
/**
|
|
522
|
+
* IntentRegistry manages all registered intents and their declared relationships.
|
|
523
|
+
*/
|
|
524
|
+
declare class IntentRegistry {
|
|
525
|
+
private readonly intents;
|
|
526
|
+
private readonly dependencies;
|
|
527
|
+
private readonly productions;
|
|
528
|
+
/**
|
|
529
|
+
* Define/register a new intent.
|
|
530
|
+
*
|
|
531
|
+
* @param name - Semantic intent name following the convention (Domain.*, Application.*, etc.)
|
|
532
|
+
* @param options - Optional relationship declarations
|
|
533
|
+
* @throws Error if an intent with the same name is already registered
|
|
534
|
+
*/
|
|
535
|
+
define<N extends IntentName, P = unknown>(name: N, options?: DefineIntentOptions): IntentCreator<N, P>;
|
|
536
|
+
/**
|
|
537
|
+
* Declare that one intent depends on / relates to another.
|
|
538
|
+
* This information is used by the DependencyGraph (future iterations) and for policy checks.
|
|
539
|
+
*
|
|
540
|
+
* @param from - The source intent (e.g. an Application operation)
|
|
541
|
+
* @param to - The target intent it depends on (e.g. a Domain event or concept)
|
|
542
|
+
*/
|
|
543
|
+
declareDependency(from: string, to: string): void;
|
|
544
|
+
/**
|
|
545
|
+
* Declare that one intent produces / emits another (e.g. use case → domain event).
|
|
546
|
+
*/
|
|
547
|
+
declareProduction(from: string, to: string): void;
|
|
548
|
+
/**
|
|
549
|
+
* Retrieve a previously defined intent creator by name.
|
|
550
|
+
*/
|
|
551
|
+
get<N extends IntentName = IntentName, P = unknown>(name: string): IntentCreator<N, P> | undefined;
|
|
552
|
+
/**
|
|
553
|
+
* List all registered intent creators.
|
|
554
|
+
*/
|
|
555
|
+
list(): IntentCreator<IntentName, unknown>[];
|
|
556
|
+
/**
|
|
557
|
+
* Get all declared dependencies for a given intent.
|
|
558
|
+
*/
|
|
559
|
+
getDependencies(intentName: string): string[];
|
|
560
|
+
/**
|
|
561
|
+
* Get all intents produced / emitted by a given intent.
|
|
562
|
+
*/
|
|
563
|
+
getProductions(intentName: string): string[];
|
|
564
|
+
/**
|
|
565
|
+
* Get all declared relationships (useful for graph generation).
|
|
566
|
+
*/
|
|
567
|
+
getAllRelationships(): IntentRelationship[];
|
|
568
|
+
/**
|
|
569
|
+
* Check if an intent name has been registered.
|
|
570
|
+
*/
|
|
571
|
+
has(name: string): boolean;
|
|
572
|
+
/**
|
|
573
|
+
* Clear the registry. Primarily useful for tests.
|
|
574
|
+
*/
|
|
575
|
+
clear(): void;
|
|
242
576
|
}
|
|
243
577
|
|
|
244
578
|
type EventSchemaFieldType = 'string' | 'number' | 'boolean' | 'object' | 'array' | 'unknown';
|
|
@@ -418,6 +752,102 @@ interface CreateProjectionRegistryOptions {
|
|
|
418
752
|
auditTrail?: AuditTrail;
|
|
419
753
|
}
|
|
420
754
|
|
|
755
|
+
/**
|
|
756
|
+
* Policy types for the Ark kernel.
|
|
757
|
+
*
|
|
758
|
+
* Policies allow declaring architectural rules that can be checked at runtime.
|
|
759
|
+
* Supports both hard policies (must never be violated) and soft policies (warnings).
|
|
760
|
+
*/
|
|
761
|
+
type PolicySeverity = 'hard' | 'soft';
|
|
762
|
+
type PolicyEnforcementMode = 'runtime' | 'static' | 'runtime-and-static' | 'advisory';
|
|
763
|
+
/**
|
|
764
|
+
* Represents a single violation of a policy.
|
|
765
|
+
*/
|
|
766
|
+
interface PolicyViolation {
|
|
767
|
+
/** Name of the policy that was violated */
|
|
768
|
+
policyName: string;
|
|
769
|
+
/** Severity level of the policy */
|
|
770
|
+
severity: PolicySeverity;
|
|
771
|
+
/** Human-readable explanation of the violation */
|
|
772
|
+
message: string;
|
|
773
|
+
/** Optional additional structured details */
|
|
774
|
+
details?: unknown;
|
|
775
|
+
}
|
|
776
|
+
/**
|
|
777
|
+
* A Policy defines a rule that can be evaluated against a context.
|
|
778
|
+
*
|
|
779
|
+
* @template Context - The shape of data the policy evaluates (e.g. { registry, events })
|
|
780
|
+
*/
|
|
781
|
+
interface Policy<Context = unknown> {
|
|
782
|
+
/** Unique name of the policy (used in violations and reporting) */
|
|
783
|
+
readonly name: string;
|
|
784
|
+
/** Whether this is a hard rule (enforced strictly) or soft (advisory) */
|
|
785
|
+
readonly severity: PolicySeverity;
|
|
786
|
+
/** Optional tags for policy classification (e.g. 'layer', 'naming') */
|
|
787
|
+
readonly tags?: readonly string[];
|
|
788
|
+
readonly owner?: string;
|
|
789
|
+
readonly version?: string;
|
|
790
|
+
readonly rationale?: string;
|
|
791
|
+
readonly enforcementMode?: PolicyEnforcementMode;
|
|
792
|
+
readonly deprecated?: boolean | string;
|
|
793
|
+
readonly replacedBy?: string;
|
|
794
|
+
/**
|
|
795
|
+
* Evaluates the policy against the given context.
|
|
796
|
+
* Return true / [] for pass, false / single violation / array for failure.
|
|
797
|
+
*/
|
|
798
|
+
check(context: Context): boolean | PolicyViolation | PolicyViolation[];
|
|
799
|
+
}
|
|
800
|
+
|
|
801
|
+
/**
|
|
802
|
+
* PolicyEngine
|
|
803
|
+
*
|
|
804
|
+
* Evaluates collections of policies against a context.
|
|
805
|
+
* Supports hard and soft policies.
|
|
806
|
+
* - Hard policies: violations cause enforcement to throw.
|
|
807
|
+
* - Soft policies: violations are reported as warnings but do not throw.
|
|
808
|
+
*/
|
|
809
|
+
|
|
810
|
+
interface PolicyEvaluationResult {
|
|
811
|
+
passed: boolean;
|
|
812
|
+
violations: PolicyViolation[];
|
|
813
|
+
hardViolations: PolicyViolation[];
|
|
814
|
+
softViolations: PolicyViolation[];
|
|
815
|
+
}
|
|
816
|
+
/**
|
|
817
|
+
* The PolicyEngine is responsible for registering policies and evaluating
|
|
818
|
+
* them against a given context.
|
|
819
|
+
*/
|
|
820
|
+
declare class PolicyEngine<Context = unknown> {
|
|
821
|
+
private readonly policies;
|
|
822
|
+
constructor(initialPolicies?: Policy<Context>[]);
|
|
823
|
+
/**
|
|
824
|
+
* Adds a policy to the engine.
|
|
825
|
+
*/
|
|
826
|
+
add(policy: Policy<Context>): void;
|
|
827
|
+
/**
|
|
828
|
+
* Returns all registered policies.
|
|
829
|
+
*/
|
|
830
|
+
getPolicies(): Policy<Context>[];
|
|
831
|
+
/**
|
|
832
|
+
* Evaluates all policies against the provided context.
|
|
833
|
+
*/
|
|
834
|
+
evaluate(context: Context): PolicyEvaluationResult;
|
|
835
|
+
/**
|
|
836
|
+
* Enforces all policies.
|
|
837
|
+
*
|
|
838
|
+
* - Soft violations are collected and can be observed (returned or logged).
|
|
839
|
+
* - Hard violations cause an error to be thrown (by default).
|
|
840
|
+
*
|
|
841
|
+
* @returns Evaluation result (including any soft violations)
|
|
842
|
+
* @throws Error if any hard policy is violated
|
|
843
|
+
*/
|
|
844
|
+
enforce(context: Context): PolicyEvaluationResult;
|
|
845
|
+
/**
|
|
846
|
+
* Clears all registered policies.
|
|
847
|
+
*/
|
|
848
|
+
clear(): void;
|
|
849
|
+
}
|
|
850
|
+
|
|
421
851
|
type EventBufferStatus = 'pending' | 'dispatched' | 'failed';
|
|
422
852
|
interface EventBufferRecord {
|
|
423
853
|
id: string;
|
|
@@ -464,7 +894,7 @@ type OutboxStore = EventBufferStore;
|
|
|
464
894
|
*/
|
|
465
895
|
|
|
466
896
|
/** Standard trace record for observability and agent consumption. */
|
|
467
|
-
type TraceRecordType = 'event.published' | 'event.rawPublish' | 'event.intercepted' | 'interceptor.error' | 'policy.hardViolation' | 'policy.softViolation' | 'layer.observedViolation' | 'handler.error' | 'hook.error';
|
|
897
|
+
type TraceRecordType = 'event.published' | 'event.rawPublish' | 'event.handoffFailed' | 'event.intercepted' | 'interceptor.error' | 'policy.hardViolation' | 'policy.softViolation' | 'layer.observedViolation' | 'handler.error' | 'hook.error';
|
|
468
898
|
/**
|
|
469
899
|
* Runtime enforcement mode for observed producer→event layer flows.
|
|
470
900
|
* - 'off': flows are recorded (for drift reports) but never enforced.
|
|
@@ -510,6 +940,15 @@ interface EventBusOptions<Context = unknown> {
|
|
|
510
940
|
enforceObservedLayerFlow?: ObservedLayerFlowMode;
|
|
511
941
|
/** Optional non-atomic event buffer for dispatch handoff. */
|
|
512
942
|
eventBuffer?: EventBufferStore;
|
|
943
|
+
/**
|
|
944
|
+
* When true, the event-buffer record written for a publish is marked
|
|
945
|
+
* `dispatched` once local delivery finishes (handlers + onPublish), or `failed`
|
|
946
|
+
* when a rethrown handler error aborts it. Use only when no external relay
|
|
947
|
+
* drains the buffer. Default: false — records stay `pending` for a
|
|
948
|
+
* consumer-owned relay (`claim` / `markDispatched`). `createArkKernel` turns
|
|
949
|
+
* this on for its default in-memory buffer only.
|
|
950
|
+
*/
|
|
951
|
+
settleBufferOnLocalDelivery?: boolean;
|
|
513
952
|
/** @deprecated Use eventBuffer. */
|
|
514
953
|
outbox?: EventBufferStore;
|
|
515
954
|
/** Stable id stamped into event metadata for this kernel/event bus instance. */
|
|
@@ -604,6 +1043,14 @@ interface EventDispatchControl {
|
|
|
604
1043
|
awaitHandlers?: boolean;
|
|
605
1044
|
runOnPublish?: boolean;
|
|
606
1045
|
tx?: unknown;
|
|
1046
|
+
/**
|
|
1047
|
+
* When false, skip local-delivery settlement of the buffer record even if the
|
|
1048
|
+
* bus settles on local delivery (the caller owns the outcome, e.g. a broker
|
|
1049
|
+
* handoff). Default: the bus `settleBufferOnLocalDelivery` option.
|
|
1050
|
+
*/
|
|
1051
|
+
settleBufferOnLocalDelivery?: boolean;
|
|
1052
|
+
/** Receives the event-buffer record written for this publish, when any. */
|
|
1053
|
+
onBufferRecord?: (record: EventBufferRecord) => void;
|
|
607
1054
|
}
|
|
608
1055
|
/**
|
|
609
1056
|
* The public EventBus interface.
|
|
@@ -1188,6 +1635,24 @@ type ArkRunRegisterOptions<T = unknown> = {
|
|
|
1188
1635
|
};
|
|
1189
1636
|
type ArkRunRegistrationHandle = ArkRunInformationPackageComponent;
|
|
1190
1637
|
|
|
1638
|
+
type ArkRunInspectorListenSource = {
|
|
1639
|
+
getInspectorSnapshot(bind: ArkRunInspectorBind): ArkRunInspectorSnapshot;
|
|
1640
|
+
requestGraph(query?: ArkRunGraphQuery): ArkRunGraph;
|
|
1641
|
+
/** OD04: pending/failed outbox summaries (EventBufferStore.list). */
|
|
1642
|
+
listInspectorOutbox?(): Promise<ArkRunInspectorOutboxMonitor>;
|
|
1643
|
+
/** OD04: workflow/saga summaries (WorkflowEngine.list). */
|
|
1644
|
+
listInspectorWorkflows?(): Promise<ArkRunInspectorWorkflowsMonitor>;
|
|
1645
|
+
/** Duck-typed kernel ports when explicit list* helpers are absent. */
|
|
1646
|
+
outbox?: {
|
|
1647
|
+
list(status?: 'pending' | 'dispatched' | 'failed'): Promise<unknown[]>;
|
|
1648
|
+
};
|
|
1649
|
+
eventBuffer?: {
|
|
1650
|
+
list(status?: 'pending' | 'dispatched' | 'failed'): Promise<unknown[]>;
|
|
1651
|
+
};
|
|
1652
|
+
workflowEngine?: {
|
|
1653
|
+
list(workflowName?: string): Promise<unknown[]>;
|
|
1654
|
+
};
|
|
1655
|
+
};
|
|
1191
1656
|
type ArkRunInspectorHandle = {
|
|
1192
1657
|
host: string;
|
|
1193
1658
|
port: number;
|
|
@@ -1200,11 +1665,6 @@ type ArkRunInspectorHandle = {
|
|
|
1200
1665
|
close(): Promise<void>;
|
|
1201
1666
|
};
|
|
1202
1667
|
|
|
1203
|
-
/**
|
|
1204
|
-
* Opt-in ArkRun inspector. HTTP is dynamically imported so constructing a
|
|
1205
|
-
* kernel does not bind a port or load `node:http`.
|
|
1206
|
-
*/
|
|
1207
|
-
|
|
1208
1668
|
type StartArkRunInspectorOptions = {
|
|
1209
1669
|
host?: string;
|
|
1210
1670
|
port?: number;
|
|
@@ -1212,24 +1672,8 @@ type StartArkRunInspectorOptions = {
|
|
|
1212
1672
|
nodeEnv?: string;
|
|
1213
1673
|
sseIntervalMs?: number;
|
|
1214
1674
|
};
|
|
1215
|
-
|
|
1216
|
-
|
|
1217
|
-
requestGraph(query?: ArkRunGraphQuery): ArkRunGraph;
|
|
1218
|
-
/** OD04: pending/failed outbox summaries (EventBufferStore.list). */
|
|
1219
|
-
listInspectorOutbox?(): Promise<ArkRunInspectorOutboxMonitor>;
|
|
1220
|
-
/** OD04: workflow/saga summaries (WorkflowEngine.list). */
|
|
1221
|
-
listInspectorWorkflows?(): Promise<ArkRunInspectorWorkflowsMonitor>;
|
|
1222
|
-
/** Duck-typed kernel ports when explicit list* helpers are absent. */
|
|
1223
|
-
outbox?: {
|
|
1224
|
-
list(status?: 'pending' | 'dispatched' | 'failed'): Promise<unknown[]>;
|
|
1225
|
-
};
|
|
1226
|
-
eventBuffer?: {
|
|
1227
|
-
list(status?: 'pending' | 'dispatched' | 'failed'): Promise<unknown[]>;
|
|
1228
|
-
};
|
|
1229
|
-
workflowEngine?: {
|
|
1230
|
-
list(workflowName?: string): Promise<unknown[]>;
|
|
1231
|
-
};
|
|
1232
|
-
};
|
|
1675
|
+
/** What the inspector reads: snapshot, graph, and optional outbox / workflow monitors. */
|
|
1676
|
+
type ArkRunInspectorSource = ArkRunInspectorListenSource;
|
|
1233
1677
|
declare function startArkRunInspector(source: ArkRunInspectorSource, options?: StartArkRunInspectorOptions): Promise<ArkRunInspectorHandle>;
|
|
1234
1678
|
|
|
1235
1679
|
/**
|
|
@@ -1353,4 +1797,4 @@ interface CreateArkKernelFromConfigOptions extends Omit<CreateArkKernelOptions,
|
|
|
1353
1797
|
}
|
|
1354
1798
|
type ArkKernelConfig = ArkCheckConfig;
|
|
1355
1799
|
|
|
1356
|
-
export {
|
|
1800
|
+
export { type TraceRecord as $, type ArkKernel as A, type EventBus as B, type CreateArkKernelOptions as C, type DependencyGraph as D, type EventContractRegistry as E, type CreateObservabilityReporterOptions as F, type GraphEdge as G, PolicyEngine as H, IntentRegistry as I, type ArkManifest as J, type WorkflowSnapshot as K, type SagaDefinition as L, type MetadataRegistry as M, type CreateWorkflowEngineOptions as N, type ObservabilityReporter as O, type ProjectionRegistry as P, type SagaInstance as Q, type ReadModelStore as R, type SagaContext as S, type WorkflowEngine as T, type ArkConfig as U, type ArkConfigLoadResult as V, type WorkflowStore as W, type DependencyInformationPackage as X, type ArkKernelConfig as Y, type CreateArkKernelFromConfigOptions as Z, type TraceRecordType as _, type AuditStore as a, type ArkRunInspectorSource as a$, type OutboxStatus as a0, type OutboxRecord as a1, type ObservabilityDriftReport as a2, ARK_RUN_COMPONENT_LIFETIMES as a3, ARK_RUN_EPHEMERAL_DEFAULT as a4, ARK_RUN_GRAPH_DEFAULT_SLICE as a5, ARK_RUN_GRAPH_NODE_KINDS as a6, ARK_RUN_GRAPH_PROCESS_EDGE_KINDS as a7, ARK_RUN_GRAPH_SCHEMA_VERSION as a8, ARK_RUN_GRAPH_SLICES as a9, type ArkRunDeliveredVia as aA, type ArkRunExtendedInfo as aB, type ArkRunGraph as aC, type ArkRunGraphEdge as aD, type ArkRunGraphEdgeKind as aE, type ArkRunGraphMatch as aF, type ArkRunGraphMatchInput as aG, type ArkRunGraphNode as aH, type ArkRunGraphNodeKind as aI, type ArkRunGraphProcessEdgeKind as aJ, type ArkRunGraphQuery as aK, type ArkRunGraphResolvedQuery as aL, type ArkRunGraphSlice as aM, type ArkRunGraphTechnicalEdgeKind as aN, type ArkRunInformationPackageComponent as aO, type ArkRunInspectorBind as aP, ArkRunInspectorBindError as aQ, type ArkRunInspectorBindInput as aR, type ArkRunInspectorHandle as aS, type ArkRunInspectorHardening as aT, type ArkRunInspectorHardeningDurability as aU, type ArkRunInspectorMonitorBuildOptions as aV, type ArkRunInspectorOutboxMonitor as aW, type ArkRunInspectorOutboxRecordSummary as aX, ArkRunInspectorProductionError as aY, type ArkRunInspectorSnapshot as aZ, type ArkRunInspectorSnapshotInput as a_, ARK_RUN_GRAPH_TECHNICAL_EDGE_KINDS as aa, ARK_RUN_INFORMATION_PACKAGE_SCHEMA_VERSION as ab, ARK_RUN_INSPECTOR_DEFAULT_HOST as ac, ARK_RUN_INSPECTOR_DEFAULT_PORT as ad, ARK_RUN_INSPECTOR_EVENTS_PATH as ae, ARK_RUN_INSPECTOR_GRAPH_PATH as af, ARK_RUN_INSPECTOR_MONITOR_SAMPLE_LIMIT as ag, ARK_RUN_INSPECTOR_OUTBOX_PATH as ah, ARK_RUN_INSPECTOR_SCHEMA_VERSION as ai, ARK_RUN_INSPECTOR_SNAPSHOT_PATH as aj, ARK_RUN_INSPECTOR_SSE_EVENT as ak, ARK_RUN_INSPECTOR_TRANSPORT_FALLBACK as al, ARK_RUN_INSPECTOR_WORKFLOWS_PATH as am, ARK_RUN_TRANSPORT_KINDS as an, type ArchitectureLayer as ao, type ArchitectureLayerConfig as ap, type ArchitectureRule as aq, type ArkManifestArchitecture as ar, type ArkManifestData as as, type ArkManifestEntityLink as at, type ArkManifestGraph as au, type ArkManifestIntent as av, type ArkManifestPolicy as aw, type ArkManifestProjection as ax, type ArkRunBrokerAdapter as ay, type ArkRunComponentLifetime as az, type AuditRecord as b, formatArkRunInspectorSseEvent as b$, type ArkRunInspectorStoreDurability as b0, type ArkRunInspectorStoreDurabilityKind as b1, type ArkRunInspectorStoreRole as b2, type ArkRunInspectorTransportFacts as b3, type ArkRunInspectorWorkflowSummary as b4, type ArkRunInspectorWorkflowsMonitor as b5, type ArkRunPublisher as b6, type ArkRunRegisterOptions as b7, type ArkRunRegistrationHandle as b8, type ArkRunSendOptions as b9, type OutboxStore as bA, type PolicyEvaluationResult as bB, type ProjectionCheckpoint as bC, type ProjectionDefinition as bD, type PublishedEventRecord as bE, type RetryPolicy as bF, type SagaStatus as bG, type SagaStep as bH, type StartArkRunInspectorOptions as bI, type TraceSink as bJ, type Unsubscribe as bK, type WorkflowDefinition as bL, type WorkflowStatus as bM, type WorkflowStep as bN, appendDecisionTape as bO, arkRunGraphQueryFromSearchParams as bP, arkRunInspectorUrl as bQ, buildArkRunInspectorHardening as bR, buildArkRunInspectorOutboxMonitor as bS, buildArkRunInspectorSnapshot as bT, buildArkRunInspectorWorkflowsMonitor as bU, buildDependencyInformationPackage as bV, classifyArkRunInspectorStoreDurability as bW, closeArkRunGraphQuery as bX, closedArkRunEphemeral as bY, closedArkRunTransportKind as bZ, formatArkRunGraphMermaid as b_, type ArkRunSendPlan as ba, type ArkRunSendPlanInput as bb, type ArkRunSendResult as bc, type ArkRunTransportKind as bd, type AuditRecordInput as be, type AuditRecordType as bf, type CorrelationId as bg, type EntityMeta as bh, type EventContractIssue as bi, type EventHandler as bj, type EventInterceptionInfo as bk, type EventInterceptor as bl, type EventInterceptorContext as bm, type EventMetadata as bn, type EventPayloadPatch as bo, type EventPayloadSchema as bp, type EventPublisher as bq, type EventSchemaField as br, type EventSchemaFieldType as bs, type FieldMeta as bt, type GraphNode as bu, type IntentRelationshipKind as bv, InvalidArkRunGraphQueryError as bw, InvalidArkRunSendOptionError as bx, type ObservabilityFlow as by, type ObservedLayerFlowMode as bz, type AuditQuery as c, isArkRunInspectorLoopbackHost as c0, isArkRunInspectorProductionEnv as c1, requestArkRunGraph as c2, resolveArkRunInspectorBind as c3, resolveArkRunSendPlan as c4, startArkRunInspector as c5, unavailableArkRunInspectorOutboxMonitor as c6, unavailableArkRunInspectorWorkflowsMonitor as c7, type CreateAuditTrailOptions as d, type AuditTrail as e, type CreateArchitectureProfileOptions as f, type ArchitectureProfile as g, type ArkCheckConfig as h, type CreateArchitectureProfileFromArkConfigOptions as i, type CreateElevenLayerArkConfigOptions as j, type EventContract as k, type DomainEvent as l, type EventContractValidationResult as m, type IntentName as n, type DefineIntentOptions as o, type IntentCreator as p, type CreateProjectionRegistryOptions as q, type PolicyViolation as r, type PolicySeverity as s, type PolicyEnforcementMode as t, type Policy as u, type IntentRelationship as v, type EventBufferStore as w, type EventBufferRecord as x, type EventBufferStatus as y, type EventBusOptions as z };
|