docs(integration): expose stable contracts for the unified native runtime (closes #95)#114
Merged
Merged
Conversation
…time Closes #95. The future unified native Simplicio runtime — coordinating simplicio-mapper, simplicio-dev-cli, simplicio-prompt, simplicio-sprint, and a local LLM runtime via llama.cpp/GGUF as one local program — depends on this repo as the fast context layer. Add a dedicated "Native Runtime Contract" section to SIMPLICIO_INTEGRATION.md that pins down what is guaranteed: - a table of every command, its `--json` payload location, the schema name, and the stable fields each schema exposes; - the three-value exit-code contract (`0` wrote/refreshed, `1` failed, `2` skipped — already-fresh treated as success); - lock and cache behavior for many concurrent local agents (`.simplicio/index.lock` exclusion, atomic temp+rename writes, diskcache per-file memoization keyed by path/size/mtime, SQLite cross- process safety); - the two equivalent invocation styles for changed-file incremental refresh (`--incremental`, `--changed-only`, `update`); - which timing/cache stats the runtime can rely on (`duration_ms` in every index payload, `counts.*` for endpoints/screens/docs, `file_count` and `precedent_count` for the main pipeline); - SemVer stability guarantees for all nine `simplicio.*/v1` schemas, cross-runtime parity (Node ↔ Python) guarded by `test_parity.py`, and the three-source `--version` check; - a six-step native-runtime adoption checklist. No code change — this PR locks in the contract that the existing CLI already implements so external consumers can build against it. https://claude.ai/code/session_01JdmemqddwFnvbceWyuDE8m
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new “Native Runtime Contract” section to SIMPLICIO_INTEGRATION.md to document the stable CLI/JSON contracts that a unified native Simplicio runtime can rely on when orchestrating simplicio-mapper as the local “fast context layer”.
Changes:
- Documented CLI commands, intended
--jsonpayload shapes, exit codes, and concurrency/lock/cache expectations for native runtime orchestration. - Documented incremental refresh semantics, timing/cost signals, and stability guarantees for
simplicio.*/v1schemas. - Added a practical adoption checklist for runtime integrators.
Comment on lines
+278
to
+290
| | Command | Path | JSON schema | Stable fields | | ||
| |---|---|---|---| | ||
| | `simplicio-mapper index <path> --json` | stdout | `simplicio.mapper-index/v1` | `status`, `fingerprint`, `project_map_path`, `precedent_path`, `file_count`, `precedent_count`, `duration_ms`, `error?`, `skipped_reason?` | | ||
| | `simplicio-mapper map [--root <dir>] [--json]` | stdout when `--json` | mirrors the index payload above | same — emit the same shape so orchestrators do not branch on command name | | ||
| | `simplicio-mapper update [--root <dir>] [--json]` | stdout when `--json` | mirrors the index payload above | same | | ||
| | `simplicio-mapper endpoints <path> --against <root> --json` | stdout | `simplicio.endpoint-inventory/v1` | `schema`, `counts.client_calls`, `counts.server_routes`, `client_calls[]`, `server_routes[]`, `missing_from_server[]` | | ||
| | `simplicio-mapper screens <path> --json` | stdout | `simplicio.screen-inventory/v1` | `schema`, `routes[]`, `personas[]`, `guards[]` | | ||
| | `simplicio-mapper docs <path> --json` | stdout | `simplicio.architecture-docs/v1` envelope | `docs_root`, `counts.files`, `files[].path`, `files[].kind` | | ||
| | `simplicio-mapper export-docs <path> --target <dir> --json` | stdout | same envelope as `docs` plus `target` | `target`, `docs_root`, `counts.files` | | ||
| | `simplicio-mapper docs <path>` (no `--json`) | `.simplicio/docs/*.md` | `simplicio.architecture-docs/v1` markdown | `architecture.md`, `layers.md`, `call-graph.md`, `modules.md`, `modules/<module>.md` | | ||
| | `simplicio-mapper index|map|update --docs-only` | `.simplicio/docs/*.md` | same markdown set | renders without rewriting JSON; useful for refresh-only-docs flows | | ||
| | `simplicio-mapper index|map|update --background` | `.simplicio/background-index.log` | best-effort log | detached refresh; lock-guarded against the foreground | | ||
|
|
Comment on lines
+297
to
+301
| | Code | Meaning | | ||
| |---|---| | ||
| | `0` | Wrote or refreshed artifacts, or an `index` run found state already-fresh and reused it (per CHANGELOG `0.6.4`). | | ||
| | `1` | Failure. JSON `status="failed"` and a non-empty `error` string are emitted when `--json` is set. | | ||
| | `2` | Skipped: fingerprint matched and artifacts were present, no work needed. The native runtime should treat exit 2 as a successful no-op, not an error. | |
Comment on lines
+335
to
+338
| The incremental refresh only re-emits `files[]` and `precedents[]` entries | ||
| whose `(path, size, mtime)` triple changed; the rest of the artifact is | ||
| preserved from the previous run. The schema, ordering, and importance scoring | ||
| remain identical to a full refresh — only the cost changes. |
Comment on lines
+342
to
+355
| The `index` command emits `duration_ms` in every JSON payload (wrote / | ||
| skipped / failed). The native runtime can use it to: | ||
|
|
||
| - detect cold-start regressions on a per-repo basis (compare `duration_ms` | ||
| for `status="wrote"` against rolling baselines); | ||
| - attribute token / time savings against a baseline that doesn't use the | ||
| mapper at all; | ||
| - decide whether to fan out to background refresh based on observed | ||
| foreground cost. | ||
|
|
||
| Per-artifact write counts are exposed under `counts.*` for the | ||
| `endpoints` / `screens` / `docs` commands. The `index` payload's | ||
| `file_count` and `precedent_count` provide an equivalent dimension for the | ||
| main mapping pipeline. |
Comment on lines
+365
to
+371
| - `simplicio-mapper --version` is sourced from `package.json`, | ||
| `pyproject.toml`, and `simplicio_mapper.__version__` simultaneously and | ||
| verified in CI by `scripts/check-version-sync.js`. | ||
| - The Node mapper at `bin/cli.js` and the Python mapper at | ||
| `simplicio_mapper.mapper` are kept in parity by | ||
| `tests/python/test_parity.py` (issue #98). Any heuristic divergence is a | ||
| bug. |
Comment on lines
+377
to
+387
| 1. Call `simplicio-mapper index <repo> --json` before each agent | ||
| dispatch; treat exit `2` as a successful no-op. | ||
| 2. Parse the JSON payload and follow `project_map_path` / | ||
| `precedent_path` for the actual artifacts. | ||
| 3. Read JSON artifacts with `json.loads`. Never tail or partially parse — | ||
| atomic writes guarantee whole-file consistency. | ||
| 4. Observe `skipped_reason="locked"`; back off and retry rather than | ||
| block. | ||
| 5. Track `duration_ms` in your telemetry to attribute speedups. | ||
| 6. Cache `fingerprint` per-agent; only re-read artifacts when the | ||
| fingerprint changes. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resumo
Fecha #95. Adiciona seção "Native Runtime Contract" no
SIMPLICIO_INTEGRATION.mddocumentando o que o runtime nativo unificado pode contar como contrato estável.Mudanças (apenas doc)
Nova seção em SIMPLICIO_INTEGRATION.md cobrindo:
--json— para cada comando (index,map,update,endpoints,screens,docs,export-docs,--docs-only,--background) lista a localização (stdout vs.simplicio/), o schema e os campos estáveis.0wrote/refreshed (inclui already-fresh),1failed (com JSONstatus="failed"),2skipped (no-op de sucesso)..simplicio/index.lockforeground/background exclusion, atomic temp+rename, diskcache keyed by path/size/mtime, SQLite cross-process safety.--incremental/--changed-only/updateequivalentes, mesmo schema/ordering/importance.duration_msem todo payload do index;counts.*em endpoints/screens/docs;file_count/precedent_countno main pipeline.simplicio.*/v1SemVer-locked; aditivo em v1, rename/remove exige v2 + ADR; cross-runtime parity (Node↔Python) coberta por Add a parity test asserting Node and Python mappers emit equivalent artifacts #98; version sync por Add a version-sync guard across package.json, pyproject.toml, and __init__.py #102.Acceptance da issue
--jsonpara map/index/query e correlatos.--incremental/--changed-only).duration_ms,counts.*).Validação
npm run lintRefs #95, #98 (parity), #102 (version sync), #97 (CI gates), #103 (test coverage), #101 (lint).
https://claude.ai/code/session_01JdmemqddwFnvbceWyuDE8m
Generated by Claude Code