Files
VCCPlusOSS/docs/development/MCP_PROJECT_RELIABILITY.md
T

101 lines
5.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Project inputs, cache safety and scoped MCP refresh
> Technical evidence extract for the VCC Plus white paper. Only reviewed contracts, mechanisms, methods, results and limitations are retained. Original validation dates and configuration limits remain historical; this export is not a new test run.
## One content-based input manifest
Project navigation entries, build snapshots, input hashes and assistant scope use
`CMOCProjectInputManifest`. Its entries identify relative path, role, inclusion
reason, content hash, relevant control permissions and whether the entry affects
the source revision/build. Excluded directory rows explain the entire subtree
without reading or hashing its generated contents. The public manifest is paged;
it contains metadata, not file bytes or private connection credentials.
Nested C headers are included recursively. Explicit configured include paths,
sources, generator prerequisites and approved support roots remain inputs.
Retained generated C is still a source input unless declared as an output.
Conventional compiler products, declared binary/disk/debug outputs, logs,
receipts and incidental evidence directories are excluded. There is no blanket
exclusion of every `build` or `generated` directory.
Projects can add these optional literal, project-relative settings:
```json
{
"resourceInputs": ["assets/questions.dat", "out/prebuilt.dat"],
"generatedInputs": [".build/shared/generated.h"],
"outputDirectories": ["out", "test-evidence"]
}
```
Explicit resources/generated inputs override soft directory exclusions; they
cannot be the same path as a concrete declared output. The arrays do not accept
shell patterns or outside-root paths. Version-control metadata stays excluded.
Included paths cannot traverse symlinks. Support remains limited to explicitly
declared regular sibling directories; an include or dependency file never grants
access to a new root.
The same product/evidence exclusions apply inside approved support folders.
Intentional native helper executables in those approved roots are retained. A
settings file inside a support folder is ordinary input data; it cannot declare
additional support roots or expand access. An explicit single-file exception
inside an excluded project folder does not re-include its siblings.
Content and relevant control permissions determine identity. Modification times
are Make scheduling hints, so touching a file does not itself change a revision.
An actual source/header/resource edit still invalidates the affected artifact
and owned run. Restricted C recipes use only their reviewed C/header set (or the
fixed Hello Disk inputs), not unrelated personal Makefiles or resources.
## Inspect and refresh a connection
- `read_project_inputs(project_id, offset?, limit?)` pages the approved manifest
and current refresh summary; `limit` is 1–256.
- `refresh_project(project_id, revision, request_id)` refreshes authorized inputs
or requests native review for a changed scope/control set. Reuse the identical
request ID for the same operation.
- `get_project_refresh(project_id, refresh_id)` reports pending, approved,
rejected or unchanged status, current revision and bounded change metadata.
Existing clean shared files refresh under their grant. The native workbench
updates clean tabs while preserving unsaved drafts. An external edit that
conflicts with a draft's saved base requires local resolution; refresh does not
discard or silently merge that draft.
New included files, recipe/generator changes, support scope changes and executable
control permissions require native review. The window shows concrete relative
paths, old/new inclusion/roles/permissions/hashes and bounded before/after text.
Approval rechecks the reviewed inputs, session and editor identity before adoption;
it does not execute Make or start a guest. Rejected/pending changes block build,
run and source-edit application, while safe status/help/approved-file inspection
and refresh polling remain available. Private credentials never appear in these
responses. A new support root's members are not read or hashed before native
approval authorizes that root.
Stale-state errors retain their ordinary error text and add structured
`error_details` with expected/current revision/artifact facts and changed relative
input paths where known. Lists include totals/truncation indicators rather than
exceeding the transport limit. Inspect the current state before retrying with
updated identities; do not silently create another run.
## Safe cache reuse
The cache is an isolated working copy. Its index and dependency provenance are
checked before reuse. Removed inputs, corrupt/missing populated-cache receipts,
or dependency files referring to missing/foreign snapshot paths cause that
working copy to be discarded and repopulated from current approved inputs.
Supported relative dependencies and valid workspace/toolchain absolute paths
retain normal incremental behavior.
The app does not rewrite arbitrary Make dependency syntax or run a project's
`clean` recipe to repair a cache. Original source, personal media and immutable
earlier build artifacts remain intact. Every included input is protected against
recipe mutation; declared outputs are distinct and can be regenerated/cleaned.
The following development stage adds [audio capture](MCP_AUDIO_CAPTURE.md) and
[verified debugging/build diagnostics](MCP_DEBUG_EVIDENCE.md). Existing
owned-worker bounds, request idempotency, verified debugging and disk provenance
remain in force.