afyx-engineering-kit 0.0.0-stage → 0.1.0-alpha.4

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 (208) hide show
  1. package/.afyx-source-revision +1 -0
  2. package/LICENSE +21 -0
  3. package/README.md +377 -2
  4. package/SECURITY.md +74 -0
  5. package/afyx-context/LICENSE +21 -0
  6. package/afyx-context/README.md +155 -0
  7. package/afyx-context/afyx-context.json +30 -0
  8. package/afyx-context/contracts/integration-v1.schema.json +34 -0
  9. package/afyx-context/package-lock.json +53 -0
  10. package/afyx-context/package.json +34 -0
  11. package/afyx-context/scripts/benchmark.mjs +39 -0
  12. package/afyx-context/scripts/build.mjs +15 -0
  13. package/afyx-context/scripts/comparative-benchmark.mjs +342 -0
  14. package/afyx-context/scripts/comparative-worker.mjs +74 -0
  15. package/afyx-context/scripts/graph-integration-e2e.mjs +188 -0
  16. package/afyx-context/scripts/integrated-dogfood.mjs +309 -0
  17. package/afyx-context/src/budget.js +166 -0
  18. package/afyx-context/src/cli.js +110 -0
  19. package/afyx-context/src/coordination.js +343 -0
  20. package/afyx-context/src/engine.js +198 -0
  21. package/afyx-context/src/errors.js +14 -0
  22. package/afyx-context/src/graph-integration-worker.js +70 -0
  23. package/afyx-context/src/graph-integration.js +373 -0
  24. package/afyx-context/src/graph-mcp-bridge.js +103 -0
  25. package/afyx-context/src/index.js +25 -0
  26. package/afyx-context/src/integrations.js +87 -0
  27. package/afyx-context/src/memory.js +255 -0
  28. package/afyx-context/src/storage.js +364 -0
  29. package/afyx-context/test-fixtures/coordination-worker.mjs +52 -0
  30. package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/__init__.py +1 -0
  31. package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/__manifest__.py +4 -0
  32. package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/models/__init__.py +1 -0
  33. package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/models/sale_order.py +5 -0
  34. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/__init__.py +1 -0
  35. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/__manifest__.py +10 -0
  36. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/models/__init__.py +2 -0
  37. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/models/sale_order.py +20 -0
  38. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/models/sale_order_audit.py +11 -0
  39. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/security/ir.model.access.csv +2 -0
  40. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/views/sale_order_views.xml +14 -0
  41. package/afyx-forge/LICENSE +55 -0
  42. package/afyx-forge/README.md +126 -0
  43. package/afyx-forge/afyx-forge.json +28 -0
  44. package/afyx-forge/bin/afyx-forge +4 -0
  45. package/afyx-forge/bin/afyx-forge.cmd +3 -0
  46. package/afyx-forge/bin/afyx-forge.js +16 -0
  47. package/afyx-forge/contracts/forge-plan-v1.schema.json +172 -0
  48. package/afyx-forge/package.json +26 -0
  49. package/afyx-forge/src/classifier.js +190 -0
  50. package/afyx-forge/src/cli.js +111 -0
  51. package/afyx-forge/src/doctor.js +105 -0
  52. package/afyx-forge/src/guidance.js +120 -0
  53. package/afyx-forge/src/index.js +273 -0
  54. package/afyx-forge/src/planning.js +107 -0
  55. package/afyx-forge/src/policy.js +109 -0
  56. package/afyx-forge/src/workflow-refiner.js +151 -0
  57. package/afyx-graph/afyx-graph.json +20 -0
  58. package/afyx-graph/engine/LICENSE +21 -0
  59. package/afyx-graph/engine/README.md +104 -0
  60. package/afyx-graph/engine/release/RELEASE-MANIFEST.json +21 -0
  61. package/afyx-graph/engine/release/SHA256SUMS +2 -0
  62. package/afyx-graph/engine/release/afyx-graph-linux-x64.tar.gz +0 -0
  63. package/afyx-graph/engine/release/afyx-graph-win32-x64.zip +0 -0
  64. package/afyx-graph/engine/scripts/distribution-contract.mjs +212 -0
  65. package/afyx-graph/engine/scripts/distribution-product.json +33 -0
  66. package/bin/afyx-engineering-kit.mjs +61 -0
  67. package/install.ps1 +1053 -0
  68. package/install.sh +617 -0
  69. package/package.json +66 -4
  70. package/scripts/afyx-capability-orchestrator.mjs +752 -0
  71. package/scripts/afyx-claude-integration.mjs +547 -0
  72. package/scripts/afyx-context-artifact.mjs +105 -0
  73. package/scripts/afyx-credential-broker.mjs +75 -0
  74. package/scripts/afyx-doctor.ps1 +152 -0
  75. package/scripts/afyx-doctor.sh +146 -0
  76. package/scripts/afyx-forge-artifact.mjs +183 -0
  77. package/scripts/afyx-global-routing-policy.md +12 -0
  78. package/scripts/afyx-global-routing.mjs +168 -0
  79. package/scripts/afyx-graph-artifact.mjs +178 -0
  80. package/scripts/afyx-host-adapters.mjs +543 -0
  81. package/scripts/afyx-host-bridge-lifecycle.mjs +174 -0
  82. package/scripts/afyx-host-bridge.mjs +288 -0
  83. package/scripts/afyx-integration-contracts.mjs +825 -0
  84. package/scripts/afyx-mcp-integration.mjs +528 -0
  85. package/scripts/afyx-modular-integration.mjs +361 -0
  86. package/scripts/afyx-modular-runtime.mjs +451 -0
  87. package/scripts/afyx-native-skill-host.mjs +124 -0
  88. package/scripts/afyx-npm-installer.mjs +486 -0
  89. package/scripts/afyx-project.ps1 +205 -0
  90. package/scripts/afyx-project.sh +207 -0
  91. package/scripts/afyx-provider-backup.mjs +1206 -0
  92. package/scripts/afyx-provider-integration.mjs +724 -0
  93. package/scripts/afyx-provider-inventory.mjs +147 -0
  94. package/scripts/afyx-security-auditor.mjs +224 -0
  95. package/scripts/afyx-skill-engineering.mjs +354 -0
  96. package/scripts/afyx-tool-family-routing.mjs +64 -0
  97. package/scripts/afyx-universal-runtime.mjs +530 -0
  98. package/scripts/alpha_acceptance_preflight.py +240 -0
  99. package/scripts/benchmark-graph-memory.mjs +96 -0
  100. package/scripts/benchmark_capability_orchestrator.mjs +64 -0
  101. package/scripts/build-windows-installer.ps1 +259 -0
  102. package/scripts/build_forge_synthetic_image.py +328 -0
  103. package/scripts/check-reference-staleness.py +71 -0
  104. package/scripts/components.json +254 -0
  105. package/scripts/contracts/afyx-capability-request-v1.schema.json +189 -0
  106. package/scripts/contracts/afyx-capability-result-v1.schema.json +32 -0
  107. package/scripts/dogfood_engineering_comparison.mjs +303 -0
  108. package/scripts/engineering-assurance.json +28 -0
  109. package/scripts/install-afyx-context.ps1 +142 -0
  110. package/scripts/install-afyx-context.sh +126 -0
  111. package/scripts/install-afyx-forge.ps1 +265 -0
  112. package/scripts/install-afyx-forge.sh +273 -0
  113. package/scripts/install-afyx-graph.ps1 +571 -0
  114. package/scripts/install-afyx-graph.sh +438 -0
  115. package/scripts/install-codex-usage-tracker.ps1 +172 -0
  116. package/scripts/lib/AfyxComponents.psm1 +399 -0
  117. package/scripts/lib/AfyxSkillLifecycle.psm1 +289 -0
  118. package/scripts/lib/AfyxTerminal.psm1 +838 -0
  119. package/scripts/lib/afyx-components.sh +256 -0
  120. package/scripts/lib/afyx-skill-lifecycle.sh +271 -0
  121. package/scripts/link-global-dev.ps1 +193 -0
  122. package/scripts/link-global-dev.sh +130 -0
  123. package/scripts/phase8-paired-evidence.mjs +195 -0
  124. package/scripts/phase8-representative-workload.mjs +771 -0
  125. package/scripts/phase8-session-recorder.mjs +157 -0
  126. package/scripts/phase8_event_ledger.py +248 -0
  127. package/scripts/phase8_evidence_discovery.py +189 -0
  128. package/scripts/prepare-g6-package.mjs +349 -0
  129. package/scripts/resolve-git-release-artifacts.mjs +321 -0
  130. package/scripts/stage-npm-release.mjs +94 -0
  131. package/scripts/validate-afyx-graph.py +203 -0
  132. package/scripts/validate-components.py +194 -0
  133. package/scripts/validate-engineering-assurance.py +281 -0
  134. package/scripts/verify-graph-archive.mjs +64 -0
  135. package/skills/afyx-context/SKILL.md +26 -0
  136. package/skills/afyx-engineering-expert/README.md +42 -0
  137. package/skills/afyx-engineering-expert/SKILL.md +70 -0
  138. package/skills/afyx-engineering-expert/assets/result-template.md +15 -0
  139. package/skills/afyx-engineering-expert/references/ai-ml-engineer.md +17 -0
  140. package/skills/afyx-engineering-expert/references/business-analyst.md +17 -0
  141. package/skills/afyx-engineering-expert/references/clean-code-engineer.md +26 -0
  142. package/skills/afyx-engineering-expert/references/code-reviewer.md +24 -0
  143. package/skills/afyx-engineering-expert/references/cybersecurity-devsecops.md +17 -0
  144. package/skills/afyx-engineering-expert/references/data-analyst-bi.md +24 -0
  145. package/skills/afyx-engineering-expert/references/data-engineer.md +24 -0
  146. package/skills/afyx-engineering-expert/references/database-administrator.md +17 -0
  147. package/skills/afyx-engineering-expert/references/debugging-specialist.md +24 -0
  148. package/skills/afyx-engineering-expert/references/embedded-iot-engineer.md +24 -0
  149. package/skills/afyx-engineering-expert/references/erp-technical-specialist.md +17 -0
  150. package/skills/afyx-engineering-expert/references/hardware-diagnostics-auditor.md +24 -0
  151. package/skills/afyx-engineering-expert/references/hardware-electronics-engineer.md +24 -0
  152. package/skills/afyx-engineering-expert/references/integration-engineer.md +24 -0
  153. package/skills/afyx-engineering-expert/references/legacy-modernization-engineer.md +24 -0
  154. package/skills/afyx-engineering-expert/references/llmops-prompt-engineer.md +24 -0
  155. package/skills/afyx-engineering-expert/references/network-engineer.md +24 -0
  156. package/skills/afyx-engineering-expert/references/performance-benchmark-engineer.md +24 -0
  157. package/skills/afyx-engineering-expert/references/platform-engineer.md +24 -0
  158. package/skills/afyx-engineering-expert/references/product-manager.md +17 -0
  159. package/skills/afyx-engineering-expert/references/qa-engineer.md +17 -0
  160. package/skills/afyx-engineering-expert/references/site-reliability-engineer.md +17 -0
  161. package/skills/afyx-engineering-expert/references/software-engineer.md +17 -0
  162. package/skills/afyx-engineering-expert/references/solutions-architect.md +17 -0
  163. package/skills/afyx-engineering-expert/references/specialists-index.md +33 -0
  164. package/skills/afyx-engineering-expert/references/subject-matter-expert.md +17 -0
  165. package/skills/afyx-engineering-expert/references/system-analyst.md +17 -0
  166. package/skills/afyx-engineering-expert/references/technical-project-manager.md +24 -0
  167. package/skills/afyx-engineering-expert/references/technical-writer.md +24 -0
  168. package/skills/afyx-engineering-expert/references/ui-ux-designer.md +17 -0
  169. package/skills/afyx-engineering-expert/workflows/ai-data-erp.md +20 -0
  170. package/skills/afyx-engineering-expert/workflows/debugging.md +10 -0
  171. package/skills/afyx-engineering-expert/workflows/discovery-design.md +11 -0
  172. package/skills/afyx-engineering-expert/workflows/implementation.md +12 -0
  173. package/skills/afyx-engineering-expert/workflows/incident-reliability.md +12 -0
  174. package/skills/afyx-engineering-expert/workflows/review-audit.md +13 -0
  175. package/skills/afyx-forge/SKILL.md +43 -0
  176. package/skills/afyx-forge/references/adaptive-policy.md +19 -0
  177. package/skills/efficient-coding/SKILL.md +33 -0
  178. package/skills/efficient-coding/references/investigation.md +27 -0
  179. package/skills/efficient-coding/references/token-efficiency.md +25 -0
  180. package/skills/efficient-coding/references/tool-routing.md +13 -0
  181. package/skills/odoo-engineering/SKILL.md +33 -0
  182. package/skills/odoo-engineering/references/common.md +9 -0
  183. package/skills/odoo-engineering/references/odoo-10.md +32 -0
  184. package/skills/odoo-engineering/references/odoo-11.md +26 -0
  185. package/skills/odoo-engineering/references/odoo-12.md +31 -0
  186. package/skills/odoo-engineering/references/odoo-13.md +27 -0
  187. package/skills/odoo-engineering/references/odoo-14.md +31 -0
  188. package/skills/odoo-engineering/references/odoo-15.md +34 -0
  189. package/skills/odoo-engineering/references/odoo-16.md +37 -0
  190. package/skills/odoo-engineering/references/odoo-17.md +37 -0
  191. package/skills/odoo-engineering/references/odoo-18.md +48 -0
  192. package/skills/odoo-engineering/references/odoo-19.md +43 -0
  193. package/skills/odoo-engineering/references/odoo-20.md +39 -0
  194. package/skills/odoo-engineering/references/reference-schema.md +16 -0
  195. package/skills/odoo-engineering/references/version-detection.md +13 -0
  196. package/tools/codex-usage/CodexUsage.psm1 +496 -0
  197. package/tools/codex-usage/codex-usage-doctor.ps1 +150 -0
  198. package/tools/codex-usage/codex-usage-pricing.json +25 -0
  199. package/tools/codex-usage/codex-usage-stop.ps1 +167 -0
  200. package/tools/codex-usage/codex-usage-watch.ps1 +250 -0
  201. package/tools/codex-usage/vscode-user-task.json +31 -0
  202. package/tools/windows-setup/SetupBootstrapper.cs +258 -0
  203. package/uninstall.ps1 +189 -0
  204. package/uninstall.sh +167 -0
  205. package/update.ps1 +95 -0
  206. package/update.sh +67 -0
  207. package/verify.ps1 +411 -0
  208. package/verify.sh +265 -0
@@ -0,0 +1 @@
1
+ 838b5b0bf1d3413579281cbd6c5250ec767ba79d
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Afyx
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,378 @@
1
- # Temporary Holding Version
1
+ # AFYX Engineering Kit
2
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.
3
+ **Local-first engineering intelligence, adaptive guidance, and evidence-driven validation for AI coding agents.**
4
+
5
+ > **Individually Reliable. Collectively Solid.**
6
+ >
7
+ > **Evidence-Led Guidance. Bounded Scopes. Strict Integrity. Reproducible Acceptance.**
8
+ >
9
+ > **Standalone by Design. Integrated by Contract. Activated by Need.**
10
+
11
+ AFYX Engineering Kit unites six independent engineering products in a
12
+ modular ecosystem for AI-assisted software development. Use each product
13
+ on its own or combine eligible capabilities through shared installation and
14
+ routing contracts. The design prioritizes source evidence, permission boundaries,
15
+ focused validation, and failure isolation over unqualified automation claims.
16
+
17
+ **Status:** Technical Alpha · **Full runtime tested:** Windows x64 and Linux x64
18
+ (WSL2 Ubuntu) · **macOS/ARM Full:** no bundled Graph archive; runtime untested ·
19
+ **Integration:** Optional and task-driven.
20
+
21
+ Graph, Forge, Context Engine, and Engineering Expert provide four foundational
22
+ engineering pillars. Efficient Coding and Odoo Engineering are **equally
23
+ recognized standalone products**, not merely auxiliary documentation.
24
+
25
+ ## Why Afyx
26
+
27
+ Ordinary coding assistants can generate plausible changes while leaving the
28
+ engineer to establish repository structure, impact, version-specific behavior,
29
+ and acceptance evidence. Afyx adds reusable engineering controls around that
30
+ workflow:
31
+
32
+ - **Structural repository intelligence** with verifiable file, symbol, call-path,
33
+ dependency, impact, and index-health evidence.
34
+ - **Cross-disciplinary engineering orchestration** that selects only the product,
35
+ architecture, security, data, reliability, implementation, ERP, or QA guidance
36
+ relevant to the task.
37
+ - **Fail-closed evaluation contracts** for controlled engineering comparison and
38
+ evidence handling.
39
+ - **Optional context reduction with exact-original recovery**, never replacing the
40
+ original when doing so would be unsafe or more expensive.
41
+ - **Transactional installation and recovery** with ownership boundaries, preview,
42
+ verification, backup, update, and uninstall behavior shared across platforms.
43
+
44
+ Afyx is aimed at engineers and technical owners who value source evidence,
45
+ bounded change, explicit limitations, and reproducible acceptance more than
46
+ unqualified automation claims.
47
+
48
+ ## Six standalone Afyx products
49
+
50
+ The ecosystem consists of **six independently usable products**. Each provides
51
+ a distinct engineering capability; no product requires the whole Kit. An installed
52
+ capability is selected only when relevant, healthy, and authorized.
53
+
54
+ | Product | Core capability | Implementation and maturity |
55
+ |---|---|---|
56
+ | [**Afyx Graph**](afyx-graph/engine/README.md) | Local indexing, structural code intelligence, symbol/dependency navigation, impact and affected-test analysis, CLI and optional MCP. | **Standalone Node.js runtime · Technical Alpha**; static evidence requires runtime/test verification. |
57
+ | [**Afyx Forge**](afyx-forge/README.md) | Deterministic task classification, engineering policies, bounded plans, and diagnostics through Forge Core; distinct evaluation infrastructure. | **Standalone Node.js CLI/API v0.1.0 · Technical Alpha**; bounded local assistive planning approved, not autonomous code changes; historical 36-cell evaluation remains `NOT_RUN`. |
58
+ | [**Afyx Efficient Coding**](docs/tool-guides/AFYX_EFFICIENT_CODING.md) | Evidence-led coding, debugging, refactoring, focused validation, and engineering reporting. | **Standalone agent skill v1.2.2 · Implemented**; guidance, not an execution engine. |
59
+ | [**Afyx Odoo Engineering**](docs/tool-guides/AFYX_ODOO_ENGINEERING.md) | Odoo-specific ORM, views, security, module development, migration, and troubleshooting. | **Standalone agent skill v1.2.0 · Implemented**; reference coverage Odoo 10–20, with target-version verification required. |
60
+ | [**Afyx Context Engine (ACE)**](afyx-context/README.md) | Conservative context reduction, local storage, integrity checks, and exact-original recovery. | **Standalone Node.js runtime v0.1.0 · Technical Alpha**; explicit Kit selection, no universal savings guarantee. |
61
+ | [**Afyx Engineering Expert**](skills/afyx-engineering-expert/README.md) | Adaptive engineering guidance across 13 disciplines and six optional workflows. | **Standalone agent skill v0.1.1 · Implemented**; final D.6 substantive acceptance remains pending. |
62
+
63
+ ### Platform services and supporting utilities
64
+
65
+ The cross-platform **installer, updater, verifier, doctor, and capability router**
66
+ are shared Kit infrastructure, **not separate products**. Optional Windows
67
+ [Afyx Codex Usage Tracking](docs/CODEX_USAGE_TRACKER.md) is a seventh registered
68
+ observability utility, not one of the six primary engineering products.
69
+
70
+ The [component registry](scripts/components.json) is authoritative for
71
+ installable IDs, presets, supported platforms, and ownership. Consult the
72
+ [Component Guide](docs/COMPONENTS.md) for detailed functionality and limitations.
73
+
74
+ ## How the products fit together
75
+
76
+ ```mermaid
77
+ flowchart TB
78
+ H["Engineer or AI coding host"]
79
+ K["Afyx Kit lifecycle and capability router"]
80
+ G["Afyx Graph"]
81
+ F["Afyx Forge"]
82
+ EC["Afyx Efficient Coding"]
83
+ O["Afyx Odoo Engineering"]
84
+ ACE["Afyx Context Engine"]
85
+ E["Afyx Engineering Expert"]
86
+
87
+ H --> K
88
+ K -.-> G
89
+ K -.-> F
90
+ K -.-> EC
91
+ K -.-> O
92
+ K -.-> ACE
93
+ K -.-> E
94
+ ```
95
+
96
+ **Diagram legend:** The solid arrow shows the Kit entry point; dashed arrows
97
+ mean **optional, task-scoped selection**, not automatic activation or a claim
98
+ that every provider integration has passed acceptance. Every Afyx product can
99
+ also run independently through its advertised interface. Installation alone
100
+ does not imply execution; user-disabled capabilities remain disabled.
101
+
102
+ Registry-based routing and interaction contracts have source-level
103
+ implementations. Full installed-host interoperability is not claimed as
104
+ accepted. Graph-to-ACE automatic MCP interception remains default **OFF**;
105
+ Forge Core offers assistive plans and has no autonomous execution authority.
106
+ The [interoperability contract](docs/AFYX_UNIVERSAL_COMPONENT_INTEROPERABILITY.md)
107
+ distinguishes approved target behavior from proven current behavior.
108
+
109
+ ## Current product status
110
+
111
+ This repository is a **Technical Alpha prerelease**. It is not Stable v1, no
112
+ formal public Alpha approval is implied, and publisher authenticity remains
113
+ unverified unless an artifact has an independently verified attestation.
114
+
115
+ - Graph, the Kit lifecycle, ACE, Efficient Coding, Odoo Engineering, and
116
+ Engineering Expert have implemented runtime or skill contracts with regression
117
+ evidence appropriate to their respective interfaces.
118
+ - ACE and Forge are included in the Full preset; Minimal and Recommended omit
119
+ them. Installation does not grant autonomous execution. Healthy installed ACE
120
+ is used only for eligible on-demand work and respects explicit OFF.
121
+ - Automatic Graph–ACE MCP interception remains unproven/default OFF; optional
122
+ consumer paths have exact-original fallback. Context measurements include
123
+ positive and negative net results—no universal savings claim is made.
124
+ - Forge Core has a real standalone assistive CLI/API and explicitly selectable
125
+ runtime on supported installation paths. This is distinct from the formal Forge
126
+ B0–B5 evaluator campaign: its 36 cells remain `NOT_RUN`; the Owner's A8 GO
127
+ applies only to bounded local assistive planning, never autonomous execution.
128
+ - Engineering Expert is usable as a skill, while final D.6 substantive review is
129
+ still outside the accepted claims.
130
+
131
+ **Verified CI checkpoint (2026-11-05):** the `dev` merge
132
+ [`e332230`](https://github.com/a5zero7/afyx-engineering-kit/commit/e332230a2c0ba162b447af1359cf591057ce26b6)
133
+ closed a Windows Vitest hook-timeout regression. The four post-merge workflows
134
+ reported `SUCCESS`: [Graph Build](https://github.com/a5zero7/afyx-engineering-kit/actions/runs/41988333699),
135
+ [Kit CI](https://github.com/a5zero7/afyx-engineering-kit/actions/runs/41988333765),
136
+ [Windows Installer](https://github.com/a5zero7/afyx-engineering-kit/actions/runs/41988333733), and
137
+ [Phase 8 Dogfood](https://github.com/a5zero7/afyx-engineering-kit/actions/runs/41988333780).
138
+ This is a CI checkpoint, **not** independent installed-product or Stable v1 acceptance.
139
+
140
+ See [Product Vision](docs/PRODUCT_VISION.md) for the maintained product contract
141
+ and [Component Guide](docs/COMPONENTS.md) for capability and limitation details.
142
+
143
+ ## Install AFYX Engineering Kit — Windows & WSL2
144
+
145
+ ### Public npm Alpha (pending release clearance)
146
+
147
+ With Node.js 22.5 or newer, the intended public registry command is:
148
+
149
+ ```bash
150
+ npx afyx-engineering-kit install
151
+ ```
152
+
153
+ Use `--preset recommended` for core engineering skills or `--preset full`
154
+ for the prebuilt Graph, Context, Forge, and applicable skills. `full` requires
155
+ Windows x64 or Linux x64 for Graph. Provider configuration is optional and
156
+ remains subject to each host's native prerequisites. Confirm the intended Alpha
157
+ version with `npm view afyx-engineering-kit@latest version`. Until the registry
158
+ lists a cleared release, use the GitHub prerelease tarball below.
159
+
160
+ ### Local Developer Setup (Bare NPX Resolution)
161
+
162
+ For local development or offline environments where `npx afyx-engineering-kit install` must resolve without contacting public registries:
163
+
164
+ Windows 11 (PowerShell 7):
165
+ ```powershell
166
+ .\scripts\link-global-dev.ps1 -Install
167
+ .\scripts\link-global-dev.ps1 -Verify
168
+ ```
169
+
170
+ WSL2 Ubuntu (Bash):
171
+ ```bash
172
+ ./scripts/link-global-dev.sh --install
173
+ ./scripts/link-global-dev.sh --verify
174
+ ```
175
+
176
+ Once linked, bare `npx` resolves locally from any directory completely offline:
177
+ ```bash
178
+ npx afyx-engineering-kit install --preset full --skip-provider-configuration
179
+ ```
180
+
181
+ To remove the link:
182
+ ```powershell
183
+ .\scripts\link-global-dev.ps1 -Uninstall
184
+ ```
185
+
186
+ ### GitHub prerelease tarball fallback
187
+
188
+ Alternatively, use the prebuilt tarball from the [v0.1.0-alpha.2 GitHub prerelease](https://github.com/a5zero7/afyx-engineering-kit/releases/tag/v0.1.0-alpha.2):
189
+
190
+ ```bash
191
+ npm exec --yes --package="https://github.com/a5zero7/afyx-engineering-kit/releases/download/v0.1.0-alpha.2/afyx-engineering-kit-0.1.0-alpha.2.tgz" -- afyx-engineering-kit install --preset full --no-build-fallback --non-interactive --skip-provider-configuration
192
+ ```
193
+
194
+ `full` installs the prebuilt Graph runtime, Context, Forge, and applicable
195
+ skills. Provider configuration is skipped by the example; select a supported
196
+ provider explicitly when you are ready to register its MCP integration. Verify
197
+ the installation with the same `npm exec --package=... --` prefix followed by
198
+ `afyx-engineering-kit verify --preset full`. Run `afyx-engineering-kit update`
199
+ with that prefix for an ownership-aware update, or `afyx-engineering-kit uninstall`
200
+ with an explicit component to remove it. See the [installation guide](docs/INSTALLATION.md)
201
+ for provider selection, recovery, and platform limits.
202
+
203
+ ## Quick start
204
+
205
+ ### Prerequisites
206
+
207
+ - Git.
208
+ - Windows PowerShell 5.1+ / PowerShell 7, or Bash 3.2+ on Linux/macOS.
209
+ - Supported AI coding host (Codex, Antigravity, or Claude Code; or run host-independent).
210
+ - Node.js 22.5+ when selecting Afyx Graph, ACE, or Forge Core.
211
+ - npm only when a local build fallback is needed.
212
+
213
+ ### 1. Clone and preview
214
+
215
+ Windows:
216
+
217
+ ```powershell
218
+ git clone https://github.com/a5zero7/afyx-engineering-kit.git
219
+ Set-Location afyx-engineering-kit
220
+ .\install.ps1 -ValidateOnly
221
+ .\install.ps1 -WhatIf -Preset recommended
222
+ ```
223
+
224
+ Linux or macOS:
225
+
226
+ ```bash
227
+ git clone https://github.com/a5zero7/afyx-engineering-kit.git
228
+ cd afyx-engineering-kit
229
+ ./install.sh --validate-only
230
+ ./install.sh --dry-run --preset recommended
231
+ ```
232
+
233
+ Preview is non-mutating. Inspect every destination and planned action before
234
+ continuing.
235
+
236
+ ### 2. Select an actual preset
237
+
238
+ | Preset | Desired components |
239
+ |---|---|
240
+ | `minimal` | Efficient Coding, Odoo Engineering |
241
+ | `recommended` | Minimal + Afyx Engineering Expert |
242
+ | `full` | Recommended + Afyx Graph, Context, Forge, and Windows-only Usage Tracking |
243
+ | `custom` | Only components repeated with `CustomComponent` / `--custom-component` |
244
+
245
+ ACE and Forge Core are included only in `full`. Installation does not authorize autonomous
246
+ Forge execution or automatic Graph MCP interception:
247
+
248
+ ```powershell
249
+ .\install.ps1 -Preset custom -CustomComponent afyx-context -Confirm:$false
250
+ .\install.ps1 -Preset custom -CustomComponent afyx-forge -Confirm:$false
251
+ ```
252
+
253
+ ```bash
254
+ ./install.sh --preset custom --custom-component afyx-context
255
+ # Forge Core has a dedicated standalone Unix installer:
256
+ ./scripts/install-afyx-forge.sh --validate-only
257
+ ```
258
+
259
+ Install Recommended:
260
+
261
+ ```powershell
262
+ .\install.ps1 -Preset recommended
263
+ ```
264
+
265
+ Supported AI coding host integrations include Codex, Antigravity, and Claude Code
266
+ (both standalone CLI and VS Code extension-only). Native provider-aware onboarding
267
+ registers integrations without changing credentials, models, or host routing:
268
+
269
+ ```powershell
270
+ .\install.ps1 -Preset full -Provider codex,antigravity,claude -ProviderScope workspace -WorkspaceRoot (Get-Location)
271
+ ```
272
+
273
+ Antigravity-only plans exclude the Codex Usage Tracking component. See the
274
+ [Installation Guide](docs/INSTALLATION.md#provider-aware-onboarding) for global
275
+ IDE/CLI skill paths, dry-run, verification, and ownership-safe rollback.
276
+
277
+ ```bash
278
+ ./install.sh --preset recommended
279
+ ```
280
+
281
+ Open a new Codex session after skill installation.
282
+
283
+ ### 3. Verify
284
+
285
+ ```powershell
286
+ .\verify.ps1 -Preset recommended
287
+ .\scripts\afyx-doctor.ps1 -ProjectPath .
288
+ ```
289
+
290
+ ```bash
291
+ ./verify.sh --preset recommended
292
+ ./scripts/afyx-doctor.sh --project .
293
+ ```
294
+
295
+ `verify` checks the desired lifecycle state. `doctor` reports local environment
296
+ and project diagnostics without installing, repairing, or calling a model.
297
+
298
+ ## First useful workflows
299
+
300
+ ### Discover and navigate a repository
301
+
302
+ ```bash
303
+ afyx-graph init . --yes
304
+ afyx-graph query getAfyxGraphDir --path .
305
+ afyx-graph explore "external state database lifecycle" --path . --max-files 4
306
+ ```
307
+
308
+ ### Review change impact
309
+
310
+ ```bash
311
+ afyx-graph impact getAfyxGraphDir --path . --depth 2
312
+ afyx-graph affected --path . src/directory.ts
313
+ ```
314
+
315
+ Graph output is static repository evidence. It does not prove runtime behavior;
316
+ run the relevant tests and runtime checks before accepting a change.
317
+
318
+ ### Plan a substantial engineering task with Forge Core
319
+
320
+ After installing the explicitly selected Forge runtime, ask it for a bounded
321
+ plan; it does not edit source files or execute tests on your behalf:
322
+
323
+ ```bash
324
+ afyx-forge doctor
325
+ afyx-forge plan --task "Trace a cross-module data consistency regression" --format markdown
326
+ ```
327
+
328
+ For source and full usage, see [Forge Core](afyx-forge/README.md). A planned
329
+ validation checklist is **not** a completed validation or formal A8 verdict.
330
+
331
+ ### Ask for a cross-disciplinary review
332
+
333
+ ```text
334
+ Use afyx-engineering-expert to review this authentication change. Cover the
335
+ architecture, threat boundary, operational failure modes, and acceptance tests;
336
+ load only the relevant disciplines.
337
+ ```
338
+
339
+ For Odoo implementation facts, pair Expert with Odoo Engineering and establish
340
+ the target Odoo major version from repository or runtime evidence.
341
+
342
+ ### Reduce and recover exact content with ACE
343
+
344
+ ```bash
345
+ afyx-context reduce --state /absolute/owned/ace-state --owner local-owner \
346
+ --session reviewed-source-sha --input request.json --budget 16000
347
+ afyx-context get --state /absolute/owned/ace-state --owner local-owner \
348
+ --session reviewed-source-sha --reference 'ace:v1:...'
349
+ ```
350
+
351
+ ACE state is local plaintext and must be protected by host filesystem controls.
352
+ References are owner/session-bound, and retrieval verifies the stored digest.
353
+
354
+ ## Lifecycle and safety
355
+
356
+ The installer inventories before mutation and distinguishes `NOT INSTALLED`,
357
+ `HEALTHY`, `INCOMPLETE`, `INVALID`, `DRIFTED`, and `UNKNOWN`. Unknown or foreign
358
+ ownership is not silently adopted. Update/repair uses staging, validation,
359
+ backup, atomic promotion, and rollback. Project Graph indexes, credentials,
360
+ providers, models, unrelated MCP entries, and external tools are preserved.
361
+
362
+ - Safe installation, update, uninstall, and recovery: [Installation Guide](docs/INSTALLATION.md)
363
+ - Component capabilities and troubleshooting: [Component Guide](docs/COMPONENTS.md)
364
+ - Read-only diagnostics: [Diagnostics](docs/DIAGNOSTICS.md)
365
+ - Product principles and maturity: [Product Vision](docs/PRODUCT_VISION.md)
366
+ - Canonical development plan: [Afyx v1 Master Roadmap](docs/AFYX_V1_MASTER_ROADMAP.md)
367
+ - Benchmark scope and interpretation: [Benchmarks](docs/BENCHMARKS.md)
368
+
369
+ ## License and third-party boundaries
370
+
371
+ License scope must be checked **per package**. The Kit root, Graph and ACE are
372
+ MIT-licensed in their respective license/metadata files; the standalone Forge
373
+ Core package currently declares `Apache-2.0` in `afyx-forge/package.json`.
374
+ Do not infer one blanket license from the umbrella README. The Phase 5/AFYX-320
375
+ native Graph/UI replacement and provenance review are recorded as completed
376
+ for their declared artifact boundary, not as a legal guarantee about every
377
+ future dependency or distribution. External tools remain under their own terms;
378
+ retain required notices and review provenance before release.
package/SECURITY.md ADDED
@@ -0,0 +1,74 @@
1
+ # Security Policy
2
+
3
+ AFYX Engineering Kit is an open-source, local-first engineering toolkit designed for AI-assisted software engineering. Security and integrity are central design tenets. This document details the threat model, security boundaries, vulnerability reporting procedure, and best practices for safe operation.
4
+
5
+ ---
6
+
7
+ ## Supported Versions
8
+
9
+ During the Technical Alpha phase, only the latest published Alpha release and the active `dev` branch receive security patches and vulnerability evaluations.
10
+
11
+ | Version | Status | Supported |
12
+ |---|---|---|
13
+ | `0.1.0-alpha.*` (latest) | Technical Alpha | Yes |
14
+ | Historical Alpha (< latest) | Superseded | No (upgrade required) |
15
+ | `< 0.1.0` | Prototype / Pre-Alpha | No |
16
+
17
+ ---
18
+
19
+ ## Reporting a Vulnerability
20
+
21
+ We take vulnerabilities seriously. If you discover a security flaw, unauthorized privilege escalation, path traversal, injection vulnerability, or credential leak in AFYX Engineering Kit:
22
+
23
+ 1. **Do not disclose publicly:** Do not open a public issue, discussion, or pull request on GitHub.
24
+ 2. **Contact:** Report via GitHub Private Vulnerability Reporting at:
25
+ `https://github.com/a5zero7/afyx-engineering-kit/security/advisories/new`
26
+ or contact the repository maintainers through the official security contact mechanism designated on the repository homepage.
27
+ 3. **Include details:**
28
+ - Affected component(s) and version.
29
+ - Operating system and shell environment.
30
+ - Minimal proof-of-concept (PoC) or reproduction steps.
31
+ - Potential impact and threat assessment.
32
+ 4. **Response time:** The maintainers will acknowledge receipt within 48 hours and coordinate remediation before public disclosure.
33
+
34
+ ---
35
+
36
+ ## Threat Model and Trust Boundaries
37
+
38
+ ### 1. Model Context Protocol (MCP) Boundaries
39
+
40
+ - **Local-first execution:** AFYX Graph provides an optional stdio MCP server (`afyx_graph`) that executes locally on the operator's machine.
41
+ - **Untrusted MCP Servers:** AFYX components interact only with explicitly configured, authorized MCP servers. The toolkit enforces strict schema validation and will never execute foreign binaries or connect to unregistered network endpoints on behalf of unauthenticated third parties.
42
+ - **Prompt Injection Defense:** MCP tool outputs (graph exploration, file contents, symbols, call paths) return repository data that may originate from untrusted repositories. Agents consuming AFYX tool outputs must treat returned source code and docstrings as passive data, never as higher-priority system instructions.
43
+
44
+ ### 2. Credential and Provider Authentication Boundaries
45
+
46
+ - **Zero credential custody:** AFYX does not broker, intercept, store, or transmit API keys, tokens, or credentials for AI coding hosts (Anthropic Claude Code, OpenAI Codex, Google Antigravity).
47
+ - **Independent provider state:** The installer and updater never mutate provider-private state, credentials, or session history. Provider configuration merges only AFYX-owned entries into host configuration files (`~/.claude.json`, `<workspace>/.mcp.json`, `mcp_config.json`, etc.) while strictly preserving unrelated entries.
48
+ - **Environment isolation:** AFYX does not read or expose host environment variables containing secrets or private tokens unless explicitly provided through designated configuration arguments.
49
+
50
+ ### 3. File System & Path Traversal Security
51
+
52
+ - **Path containment:** All archive extraction routines, path sanitizers, and installer scripts validate that target paths remain strictly inside intended installation roots.
53
+ - **Reparse points and symlinks:** Archive extraction rejects directory traversal sequences (`..`), absolute paths, and Windows junction/reparse points or Unix symlinks that could escape designated directories.
54
+ - **Transactional modifications:** Configuration and skill file updates perform pre-modification backups and atomic writes (`atomicJson` / transactional swap) to prevent partial writes or corruption upon unexpected interruption.
55
+
56
+ ### 4. Package & Archive Provenance
57
+
58
+ - **Precompiled archive verification:** All precompiled Graph binaries are validated against an authoritative `RELEASE-MANIFEST.json` and `SHA256SUMS`.
59
+ - **Integrity verification:** Checksums are computed and verified before extraction. Corrupted, truncated, or tampered archives trigger immediate fail-closed aborts without executing fallback compilations or executing untrusted code.
60
+ - **Deterministic source revision stamping:** Every official release candidate contains a validated `.afyx-source-revision` matching the exact Git commit from which it was built.
61
+
62
+ ### 5. Package Lifecycle Scripts
63
+
64
+ - **No arbitrary postinstall execution:** The npm package does not execute invasive postinstall scripts that modify system PATH, install daemons, or mutate user files without explicit invocation.
65
+ - **Explicit user command:** Installation and updates execute only when the operator explicitly invokes `npx afyx-engineering-kit install` or related CLI commands.
66
+
67
+ ---
68
+
69
+ ## Operational Recommendations (Least Privilege)
70
+
71
+ 1. **Run with least privilege:** Do not run AFYX installers, CLI commands, or MCP servers as `Administrator` (Windows) or `root` (Linux/macOS). User-level permissions are sufficient.
72
+ 2. **Review repository sources:** When indexing third-party repositories with AFYX Graph, be aware that static analysis reads repository files. Ensure repositories from untrusted sources do not contain malicious executable files or exploit payloads.
73
+ 3. **Review provider scopes:** Prefer workspace-scoped MCP configuration (`<workspace>/.mcp.json` or `.agents/mcp_config.json`) when working on isolated repositories to minimize the surface area of global host configuration.
74
+ 4. **Keep runtimes updated:** Ensure Node.js is kept up to date with the latest LTS security releases.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Afyx
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,155 @@
1
+ # Afyx Context Engine
2
+
3
+ **Standalone local context optimization — Technical Alpha v0.1.0.**
4
+
5
+ Afyx Context Engine (ACE) is an Afyx-owned, standalone Node.js component for
6
+ conservative context reduction with byte-exact original recovery. It does not
7
+ require Afyx Graph, Forge, Engineering Expert, an external proxy, or the Kit installer.
8
+
9
+ ## API
10
+
11
+ ```js
12
+ import { AfyxContextEngine } from '@a5zero7/afyx-context';
13
+
14
+ const engine = new AfyxContextEngine({
15
+ stateDir: 'C:\\owned\\absolute\\ace-state',
16
+ ownerId: 'agent-owner',
17
+ sessionId: 'session-1',
18
+ // Optional bounded coordination controls (defaults: 5000 ms / 25 ms).
19
+ lockTimeoutMs: 5_000,
20
+ lockRetryMs: 25,
21
+ });
22
+
23
+ const result = engine.reduce({
24
+ budgetChars: 16_000,
25
+ segments: [
26
+ { id: 'diagnostic', classification: 'diagnostic', content: 'exact failure text' },
27
+ { id: 'output-1', content: 'repeated tool output' },
28
+ { id: 'output-2', content: 'repeated tool output' },
29
+ ],
30
+ });
31
+
32
+ const original = engine.retrieve(result.items[2].reference);
33
+ ```
34
+
35
+ `diagnostic`, `security`, and `source-evidence` segments remain inline. ACE
36
+ only replaces normal content when the stable reference is smaller. If the
37
+ budget cannot safely represent the complete selection, ACE returns all
38
+ original content in `passthrough` mode.
39
+
40
+ The state directory must be absolute, empty or already bound to the same
41
+ owner, and not itself a symbolic link. References are bound to both owner and
42
+ session. A content hash is verified on every retrieval. Original blobs and
43
+ session metadata are committed through owned temporary files followed by
44
+ `fsync` and rename. A retry can adopt a complete orphan blob left by an
45
+ interruption; malformed metadata and corrupt existing blobs fail closed.
46
+
47
+ Every state read and mutation participates in one local, state-root-wide
48
+ exclusive lock. The deliberately coarse scope protects first initialization,
49
+ all sessions, and the shared content-addressed store across cooperating local
50
+ processes on Windows, Linux, and macOS. Lock acquisition is bounded; contention
51
+ reports `LOCK_TIMEOUT`. A lock is recovered only on the same host after the OS
52
+ proves that its recorded PID is absent. A present or unverifiable PID—including
53
+ a possible reused PID—never authorizes removal. Missing, foreign, or ambiguous
54
+ ownership fails closed with `LOCK_RECOVERY_UNSAFE`; lock age alone is never
55
+ recovery evidence.
56
+
57
+ After a verified process interruption, complete content temporaries are adopted
58
+ only after SHA-256 validation. Complete uncommitted session metadata is removed
59
+ without replacing the last committed session, so references cannot expose an
60
+ interrupted write. Unknown files and ambiguous coordination artifacts are not
61
+ deleted automatically.
62
+
63
+ ## CLI
64
+
65
+ ```text
66
+ afyx-context reduce --state <absolute-path> --owner <id> --session <id> --input <request.json|-> [--budget <chars>]
67
+ afyx-context get --state <absolute-path> --owner <id> --session <id> --reference <ace:v1:...>
68
+ ```
69
+
70
+ Build and test without third-party runtime dependencies:
71
+
72
+ ```text
73
+ npm ci
74
+ npm run build:clean
75
+ npm test
76
+ npm run test:benchmark
77
+ ```
78
+
79
+ ## Installation and activation status
80
+
81
+ ACE is an explicit, optional Kit component (`afyx-context`), absent from
82
+ `minimal`, `recommended` and `full`. The runtime can operate completely alone,
83
+ and a supported provider may discover its on-demand companion skill after an
84
+ explicit installation. A healthy installed component being eligible for a task
85
+ is **not** the same as ACE executing or reducing output.
86
+
87
+ Explicit `AFYX_CONTEXT_OPT_IN=0` and user/provider OFF settings must be honored.
88
+ Automatic Graph MCP interception is still a separate, default-OFF path; no
89
+ universal net-token or cost savings are claimed. See the
90
+ [Kit Component Guide](../docs/COMPONENTS.md#afyx-context-engine) and
91
+ [installation guide](../docs/INSTALLATION.md#ace-standalone-versus-kit-managed).
92
+
93
+ ## Optional integration
94
+
95
+ `contracts/integration-v1.schema.json` defines `ace.integration/v1` for Graph,
96
+ Engineering Expert, Forge, and Kit consumers. `createOptionalIntegrationAdapter`
97
+ catches an unavailable/failed ACE and returns original content, so the consumer
98
+ remains independently functional. The Kit can install, update, verify, repair,
99
+ and uninstall ACE as a managed explicit component, but ACE is absent from all
100
+ implicit presets and installation never enables a consumer integration.
101
+
102
+ AFYX-293 adds the first real consumer as a separate, default-OFF bridge. It does
103
+ not alter Graph's CLI, API, MCP tools, or default responses:
104
+
105
+ ```js
106
+ import { createGraphAceConsumer, deriveGraphAceIdentity } from '@a5zero7/afyx-context';
107
+
108
+ const sourceIdentity = 'git:reviewed-source-sha';
109
+ const identity = deriveGraphAceIdentity({
110
+ projectRoot,
111
+ sourceIdentity,
112
+ consumerId: 'local-codex-session',
113
+ });
114
+ const consumer = createGraphAceConsumer({
115
+ enabled: true,
116
+ stateDir: absoluteOwnedAceState,
117
+ ...identity,
118
+ timeoutMs: 5_000,
119
+ });
120
+ const output = await consumer.execute({
121
+ executeGraph: (toolName, args) => graphToolHandler.execute(toolName, args),
122
+ toolName: 'afyx_graph_search',
123
+ args: { query: 'target symbol' },
124
+ projectRoot,
125
+ sourceIdentity,
126
+ });
127
+ ```
128
+
129
+ The bridge runs Graph first and retains its validated result as the authoritative
130
+ fallback. ACE runs only after explicit enablement in an owned local Node child
131
+ process with a distinct OS PID. Timeout terminates that child and waits for its
132
+ exit before returning the exact Graph result; an unconfirmed termination fails
133
+ closed instead of reporting completion while mutation may continue. Disabled,
134
+ unavailable, malformed, or corrupt ACE also returns the exact Graph result.
135
+ `explore`, `files`, `node`, and diagnostic output is protected and bypasses the
136
+ ACE worker because it must remain inline byte-for-byte. References are
137
+ recoverable only through the same
138
+ owner/session; invalid or corrupt recovery fails closed. Callers should use
139
+ `deriveGraphAceIdentity` to bind an owner to the canonical project/consumer and a
140
+ session to the exact source identity.
141
+
142
+ Malformed or unavailable optional integration requests return a bounded
143
+ fallback. `originalInput` retains the supplied input, and `originalComplete`
144
+ states whether `renderedContext` contains its complete render.
145
+
146
+ The v1 boundary accepts at most 1,024 segments, 1 MiB content and 64 KiB
147
+ provenance per segment, 8 MiB aggregate request content, 512-byte segment and
148
+ owner/session identities, and 10 MiB CLI input. State/session metadata are
149
+ bounded at 64 KiB/16 MiB; a stored blob is bounded at 1 MiB, a session at
150
+ 100,000 unique contents, and provenance at 256 observations per digest.
151
+
152
+ Coordination is local and exclusive, not distributed. A process-liveness check
153
+ that is unavailable, cross-host, or inconclusive requires operator inspection
154
+ instead of automatic lock removal. Stored content remains local plaintext, and
155
+ the caller owns filesystem access control and retention policy.