101 lines
5.4 KiB
Markdown
101 lines
5.4 KiB
Markdown
# 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.
|