@directive-run/knowledge 1.0.1 → 1.1.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.
Files changed (5) hide show
  1. package/README.md +2 -1
  2. package/core/schema-types.md +4 -1
  3. package/core/system-api.md +41 -1
  4. package/package.json +7 -5
  5. package/sitemap.md +179 -0
package/README.md CHANGED
@@ -13,8 +13,9 @@ This package is the **source of truth** for all Directive coding knowledge used
13
13
  |-----------|-------|-------------|
14
14
  | `core/` | 13 | Core Directive knowledge (modules, constraints, resolvers, etc.) |
15
15
  | `ai/` | 12 | AI orchestrator knowledge (agents, streaming, guardrails, etc.) |
16
- | `examples/` | 32 | Extracted examples (auto-generated, DOM wiring stripped) |
16
+ | `examples/` | 37 | Extracted examples (auto-generated, DOM wiring stripped) |
17
17
  | `api-skeleton.md` | 1 | Auto-generated API reference skeleton |
18
+ | `sitemap.md` | 1 | Auto-generated docs site sitemap (125+ pages) |
18
19
 
19
20
  ## Programmatic API
20
21
 
package/core/schema-types.md CHANGED
@@ -18,9 +18,12 @@ What kind of value?
18
18
  ├── Union → t.union(t.string(), t.number())
19
19
  ├── Map/Set → t.object<Map<K,V>>() or t.object<Set<T>>()
20
20
  ├── Date → t.object<Date>() or t.number() for timestamps
21
- └── Unknown/any → t.object<unknown>()
21
+ ├── Unknown/any → t.object<unknown>()
22
+ └── Any type + metadata → t.string().meta({ label: "Email", tags: ["pii"] })
22
23
  ```
23
24
 
25
+ All builders support `.meta({ label, description, category, color, tags })` for devtools/AI annotations. Chains with other methods: `t.string().meta({...}).nullable()`.
26
+
24
27
  ## Primitive Types
25
28
 
26
29
  ```typescript
package/core/system-api.md CHANGED
@@ -177,10 +177,50 @@ inspection.inflight;
177
177
  // Unmet requirements (no matching resolver)
178
178
  inspection.unmet;
179
179
 
180
- // Explain why a requirement exists
180
+ // Explain why a requirement exists (uses meta.label + meta.description)
181
181
  const explanation = system.explain("req-123");
182
182
  ```
183
183
 
184
+ ## Definition Meta
185
+
186
+ Attach optional metadata to any definition for debugging, devtools, and AI context:
187
+
188
+ ```typescript
189
+ // On constraints, resolvers, effects — meta field
190
+ constraints: {
191
+ needsAuth: {
192
+ when: (f) => !f.user,
193
+ require: { type: "LOGIN" },
194
+ meta: { label: "Requires Auth", category: "auth", tags: ["critical"] },
195
+ },
196
+ },
197
+
198
+ // On derivations — { compute, meta } object form
199
+ derive: {
200
+ displayName: {
201
+ compute: (f) => `${f.first} ${f.last}`,
202
+ meta: { label: "Display Name" },
203
+ },
204
+ },
205
+
206
+ // On facts — chainable .meta()
207
+ schema: { facts: { email: t.string().meta({ label: "Email", tags: ["pii"] }) } },
208
+
209
+ // On modules
210
+ meta: { label: "Auth Module", category: "auth" },
211
+
212
+ // O(1) accessor
213
+ system.meta.constraint("needsAuth")?.label; // "Requires Auth"
214
+ system.meta.fact("email")?.tags; // ["pii"]
215
+ system.meta.module("auth")?.label; // "Auth Module"
216
+
217
+ // Bulk queries
218
+ system.meta.byCategory("auth"); // MetaMatch[] — all auth definitions
219
+ system.meta.byTag("pii"); // MetaMatch[] — all PII-tagged fields
220
+ ```
221
+
222
+ Meta is frozen at registration (Object.create(null) + Object.freeze). Zero hot-path cost. See [Definition Meta docs](https://directive.run/docs/advanced/meta).
223
+
184
224
  ## Lifecycle
185
225
 
186
226
  ```typescript
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@directive-run/knowledge",
3
- "version": "1.0.1",
3
+ "version": "1.1.0",
4
4
  "description": "Knowledge files, examples, and validation for Directive — the constraint-driven TypeScript runtime.",
5
5
  "license": "(MIT OR Apache-2.0)",
6
6
  "author": "Jason Comes",
@@ -42,7 +42,8 @@
42
42
  "core",
43
43
  "ai",
44
44
  "examples",
45
- "api-skeleton.md"
45
+ "api-skeleton.md",
46
+ "sitemap.md"
46
47
  ],
47
48
  "devDependencies": {
48
49
  "@types/node": "^25.2.0",
@@ -50,12 +51,13 @@
50
51
  "tsx": "^4.19.2",
51
52
  "typescript": "^5.7.2",
52
53
  "vitest": "^3.0.0",
53
- "@directive-run/core": "1.0.1",
54
- "@directive-run/ai": "1.0.1"
54
+ "@directive-run/core": "1.1.0",
55
+ "@directive-run/ai": "1.1.0"
55
56
  },
56
57
  "scripts": {
57
- "build": "tsx scripts/generate-api-skeleton.ts && tsx scripts/extract-examples.ts && tsup",
58
+ "build": "tsx scripts/generate-api-skeleton.ts && tsx scripts/generate-sitemap.ts && tsx scripts/extract-examples.ts && tsup",
58
59
  "generate": "tsx scripts/generate-api-skeleton.ts",
60
+ "generate-sitemap": "tsx scripts/generate-sitemap.ts",
59
61
  "extract-examples": "tsx scripts/extract-examples.ts",
60
62
  "validate": "tsx scripts/validate-knowledge.ts",
61
63
  "test": "tsx scripts/validate-knowledge.ts && vitest run",
package/sitemap.md ADDED
@@ -0,0 +1,179 @@
1
+ # Directive Documentation Sitemap
2
+
3
+ > Auto-generated from the docs site navigation. Do not edit manually.
4
+ > Run `pnpm --filter @directive-run/knowledge generate-sitemap` to refresh.
5
+
6
+ Website: https://directive.run
7
+
8
+ ## Docs
9
+
10
+ ### Getting Started
11
+ - [Quick Start](https://directive.run/docs/quick-start)
12
+ - [Why Directive](https://directive.run/docs/why-directive)
13
+ - [Installation](https://directive.run/docs/installation)
14
+ - [Core Concepts](https://directive.run/docs/core-concepts)
15
+ - [Comparison](https://directive.run/docs/comparison)
16
+ - [Choosing Primitives](https://directive.run/docs/choosing-primitives)
17
+
18
+ ### Core API
19
+ - [Overview](https://directive.run/docs/core-api)
20
+ - [Module & System](https://directive.run/docs/module-system)
21
+ - [Facts](https://directive.run/docs/facts)
22
+ - [Derivations](https://directive.run/docs/derivations)
23
+ - [Constraints](https://directive.run/docs/constraints)
24
+ - [Resolvers](https://directive.run/docs/resolvers)
25
+ - [Effects](https://directive.run/docs/effects)
26
+ - [Events](https://directive.run/docs/events)
27
+ - [Schema & Types](https://directive.run/docs/schema-overview)
28
+ - [API Reference](https://directive.run/docs/api/core)
29
+ - [Type Reference](https://directive.run/docs/api/types)
30
+
31
+ ### Framework Adapters
32
+ - [Overview](https://directive.run/docs/adapters/overview)
33
+ - [React](https://directive.run/docs/adapters/react)
34
+ - [React API](https://directive.run/docs/api/react)
35
+ - [Vue](https://directive.run/docs/adapters/vue)
36
+ - [Vue API](https://directive.run/docs/api/vue)
37
+ - [Svelte](https://directive.run/docs/adapters/svelte)
38
+ - [Svelte API](https://directive.run/docs/api/svelte)
39
+ - [Solid](https://directive.run/docs/adapters/solid)
40
+ - [Solid API](https://directive.run/docs/api/solid)
41
+ - [Lit](https://directive.run/docs/adapters/lit)
42
+ - [Lit API](https://directive.run/docs/api/lit)
43
+ - [Vanilla](https://directive.run/docs/adapters/vanilla)
44
+ - [Vanilla API](https://directive.run/docs/api/vanilla)
45
+
46
+ ### Data Fetching
47
+ - [Overview](https://directive.run/docs/data-fetching/overview)
48
+ - [Queries](https://directive.run/docs/data-fetching/queries)
49
+ - [Mutations](https://directive.run/docs/data-fetching/mutations)
50
+ - [Subscriptions](https://directive.run/docs/data-fetching/subscriptions)
51
+ - [Infinite Queries](https://directive.run/docs/data-fetching/infinite)
52
+ - [Convenience API](https://directive.run/docs/data-fetching/convenience)
53
+ - [GraphQL](https://directive.run/docs/data-fetching/graphql)
54
+ - [Explain & Debug](https://directive.run/docs/data-fetching/explain)
55
+
56
+ ### Advanced
57
+ - [Overview](https://directive.run/docs/advanced/overview)
58
+ - [Multi-Module](https://directive.run/docs/advanced/multi-module)
59
+ - [Runtime Dynamics](https://directive.run/docs/advanced/runtime)
60
+ - [History & Snapshots](https://directive.run/docs/advanced/history)
61
+ - [SSR & Hydration](https://directive.run/docs/advanced/ssr)
62
+ - [Error Boundaries](https://directive.run/docs/advanced/errors)
63
+ - [Definition Meta](https://directive.run/docs/advanced/meta)
64
+
65
+ ### Plugins
66
+ - [Overview](https://directive.run/docs/plugins/overview)
67
+ - [Logging](https://directive.run/docs/plugins/logging)
68
+ - [DevTools](https://directive.run/docs/plugins/devtools)
69
+ - [Persistence](https://directive.run/docs/plugins/persistence)
70
+ - [Performance](https://directive.run/docs/plugins/performance)
71
+ - [Circuit Breaker](https://directive.run/docs/plugins/circuit-breaker)
72
+ - [Observability](https://directive.run/docs/plugins/observability)
73
+ - [Custom Plugins](https://directive.run/docs/plugins/custom)
74
+
75
+ ### Testing
76
+ - [Overview](https://directive.run/docs/testing/overview)
77
+ - [Mock Resolvers](https://directive.run/docs/testing/mock-resolvers)
78
+ - [Fake Timers](https://directive.run/docs/testing/fake-timers)
79
+ - [Assertions](https://directive.run/docs/testing/assertions)
80
+ - [Test Async Chains](https://directive.run/docs/guides/test-async-chains)
81
+
82
+ ### Examples
83
+ - [Number Match](https://directive.run/docs/examples/counter)
84
+ - [Auth Flow](https://directive.run/docs/examples/auth-flow)
85
+ - [Shopping Cart](https://directive.run/docs/examples/shopping-cart)
86
+ - [Async Chains](https://directive.run/docs/examples/async-chains)
87
+ - [Form Wizard](https://directive.run/docs/examples/form-wizard)
88
+ - [Sudoku](https://directive.run/docs/examples/sudoku)
89
+ - [Checkers](https://directive.run/docs/examples/checkers)
90
+ - [Time Machine](https://directive.run/docs/examples/time-machine)
91
+ - [Error Boundaries](https://directive.run/docs/examples/error-boundaries)
92
+ - [Fraud Analysis](https://directive.run/docs/examples/fraud-analysis)
93
+ - [Dashboard Loader](https://directive.run/docs/examples/dashboard-loader)
94
+
95
+ ### Guides
96
+ - [Overview](https://directive.run/docs/guides/overview)
97
+ - [Loading & Error States](https://directive.run/docs/guides/loading-states)
98
+ - [Authentication Flow](https://directive.run/docs/guides/auth-flow)
99
+ - [Optimistic Updates](https://directive.run/docs/guides/optimistic-updates)
100
+ - [Shopping Cart Rules](https://directive.run/docs/guides/shopping-cart)
101
+ - [Multi-Step Form Wizard](https://directive.run/docs/guides/form-wizard)
102
+
103
+ ### Async Chains Across Modules
104
+ - [Role-Based Permissions](https://directive.run/docs/guides/permissions)
105
+ - [Batch Mutations](https://directive.run/docs/guides/batch-mutations)
106
+
107
+ ## AI
108
+
109
+ ### Integration Guides
110
+ - [Overview](https://directive.run/docs/works-with/overview)
111
+ - [Redux](https://directive.run/docs/works-with/redux)
112
+ - [Zustand](https://directive.run/docs/works-with/zustand)
113
+ - [XState](https://directive.run/docs/works-with/xstate)
114
+ - [React Query](https://directive.run/docs/works-with/react-query)
115
+ - [Web Worker](https://directive.run/docs/works-with/worker)
116
+
117
+ ### Foundations
118
+ - [Overview](https://directive.run/ai/overview)
119
+ - [Running Agents](https://directive.run/ai/running-agents)
120
+ - [Resilience & Routing](https://directive.run/ai/resilience-routing)
121
+ - [Comparison](https://directive.run/ai/comparison)
122
+ - [Tutorial](https://directive.run/ai/tutorial)
123
+ - [Troubleshooting](https://directive.run/ai/troubleshooting)
124
+
125
+ ### Agent Orchestrator
126
+ - [Overview](https://directive.run/ai/orchestrator)
127
+ - [Guardrails](https://directive.run/ai/guardrails)
128
+ - [Streaming](https://directive.run/ai/streaming)
129
+ - [Memory](https://directive.run/ai/memory)
130
+
131
+ ### Multi-Agent Orchestrator
132
+ - [Overview](https://directive.run/ai/multi-agent)
133
+ - [Execution Patterns](https://directive.run/ai/patterns)
134
+ - [Communication](https://directive.run/ai/communication)
135
+ - [Cross-Agent State](https://directive.run/ai/cross-agent-state)
136
+ - [Tasks](https://directive.run/ai/tasks)
137
+ - [Self-Healing](https://directive.run/ai/self-healing)
138
+
139
+ ### Infrastructure
140
+ - [MCP Integration](https://directive.run/ai/mcp)
141
+ - [RAG Enricher](https://directive.run/ai/rag)
142
+ - [SSE Transport](https://directive.run/ai/sse-transport)
143
+ - [Semantic Cache](https://directive.run/ai/semantic-cache)
144
+
145
+ ### Observability
146
+ - [Debug Timeline](https://directive.run/ai/debug-timeline)
147
+ - [Pattern Checkpoints](https://directive.run/ai/checkpoints)
148
+ - [Breakpoints & Checkpoints](https://directive.run/ai/breakpoints)
149
+ - [DevTools](https://directive.run/ai/devtools)
150
+
151
+ ### Security & Compliance
152
+ - [Overview](https://directive.run/ai/security/overview)
153
+ - [PII Detection](https://directive.run/ai/security/pii)
154
+ - [Prompt Injection](https://directive.run/ai/security/prompt-injection)
155
+ - [Audit Trail](https://directive.run/ai/security/audit)
156
+ - [GDPR/CCPA](https://directive.run/ai/security/compliance)
157
+
158
+ ### Examples
159
+ - [Chat](https://directive.run/ai/examples/chat)
160
+ - [Research Pipeline](https://directive.run/ai/examples/research-pipeline)
161
+ - [Safety Shield](https://directive.run/ai/examples/safety-shield)
162
+ - [Checkpoint](https://directive.run/ai/examples/checkpoint)
163
+ - [Fraud Analysis](https://directive.run/ai/examples/fraud-analysis)
164
+ - [Pitch Deck](https://directive.run/ai/examples/pitch-deck)
165
+ - [Data Pipeline](https://directive.run/ai/examples/data-pipeline)
166
+ - [Code Review](https://directive.run/ai/examples/code-review)
167
+
168
+ ### Human Approval Workflows
169
+ - [Control AI Costs](https://directive.run/ai/guides/control-ai-costs)
170
+
171
+ ### Validate Structured Output
172
+ - [Handle Agent Errors](https://directive.run/ai/guides/handle-agent-errors)
173
+
174
+ ### Stream Agent Responses
175
+ - [Multi-Step Pipeline](https://directive.run/ai/guides/multi-step-pipeline)
176
+
177
+ ### Test Without LLM Calls
178
+ - [DAG Pipeline](https://directive.run/ai/guides/dag-pipeline)
179
+ - [Goal Pipeline](https://directive.run/ai/guides/goal-pipeline)