Files
marqdo-cli/spec/analysis-v1.md
T
cflmy 55dcb57553 feat(analysis): Analysis v2 logical identity and resource projection (B-06 B-07)
- add ProjectIdentity (manifest root instance or workspace snapshot digest)
  and remove absolute-path root ids from Analysis bytes
- replace the resources count with an addressable array over the two real
  marqdo-ir resource kinds (formula, code), including unit/span/payload digest
  and code language
- project diagnostics by module/relative path/span, removing machine paths
- define the digest as SHA-256 of the exact emitted bytes so consumers can
  verify it; Trace binds to the same digest
- add analysis-v2 spec and JSON schema, supersede v1, update the independent
  Python consumer, schemas and docs
- tests: location-independent byte equality and resource addressing
2026-11-20 12:58:58 +08:00

4.7 KiB

Marqdo Analysis v1

Status: superseded by Analysis v2; never released, do not write v1. Kept as history. This was the M0.6 R4 read-only projection; it is not a dump of marqdo-ir.

1. Invariants

check --emit:

  • never executes the document, loads a plugin shared library, starts a foreign kernel or imports a module implicitly;
  • validates the loaded program first; on a compile error it writes no artifact and removes a stale file at the target path;
  • writes atomically (temporary file + rename) only after a successful check;
  • is deterministic: the same source, tool version and project path produce byte-identical JSON (no timestamps, no random ids);
  • exposes no private Rust layout, optimization instruction or host pointer.

2. Top-level shape

{
  "schema": "marqdo.analysis",
  "schema_version": 1,
  "producer": {"name": "marqdo", "version": "0.1.0", "markdown_profile": "marqdo.md.v1"},
  "project": {"root_id": "sha256:...", "lock_digest": "sha256:..."},
  "modules": [],
  "diagnostics": []
}
  • root_id is a digest of the normalized project root used for this run.
  • lock_digest is a digest of marqdo.lock, or "" when absent.
  • Modules are sorted by canonical id; arrays keep source order.
  • schema_version is a major version. Additive optional fields are allowed; removing/renaming fields or changing units/types requires a major bump.

3. Modules

{
  "id": "root:default::index.mq.md",
  "package_instance_id": "root:default",
  "relative_path": "index.mq.md",
  "source_digest": "<sha256 hex>",
  "units": [],
  "functions": [],
  "imports": [],
  "references": [],
  "calls": [],
  "resources": 0
}

Module identity is the package-aware ModuleId from spec/references.md §2.1. source_digest hashes the exact source bytes.

3.1 Units

Each unit has id, kind (root/namespace/function/section), name, level, span ({start,end} byte offsets) and optionally function.

3.2 Functions and signatures

{
  "id": "root:default::index.mq.md::数学.阶乘",
  "unit_id": "root:default::index.mq.md#数学/阶乘",
  "local_name": "阶乘",
  "namespace": "数学",
  "span": {"start": 0, "end": 100},
  "heading_span": {"start": 0, "end": 10},
  "signature": {
    "kind": "inferred",
    "params": [{"name": "n", "required": true, "type": null, "default": null, "span": {"start": 0, "end": 0}}]
  },
  "effects": ["unknown"],
  "body": []
}

kind is explicit or inferred. Inferred signatures only accept named arguments. effects is a conservative summary; unknown is not a proof of purity. Dynamic ABI/Foreign targets remain unknown unless a descriptor says otherwise.

3.3 Normalized body nodes

Body nodes use a small stable language, never internal IR serialization:

  • literal (type: int/float/text/bool/none, value when present);
  • variable, list, record, member, index;
  • unary (not/neg/pos) and binary (or, and, eq, ne, lt, le, gt, ge, add, sub, mul, div, floor_div, mod, pow);
  • call with callee and args;
  • assign, expression, call_site, branch (ordered arms), loop, return.

Every node carries a byte span. Nodes outside the supported public subset must be marked unsupported (future extension), never silently given invented semantics.

3.4 Imports, references and calls

  • imports[]: {alias, target, span, resolved}; resolved is a module id or null. Imports stay explicit.
  • references[]: Markdown link edges with {source, url, span, state, target_module, target_unit}. state is resolved, unresolved or external; a failed resolution is never disguised as bound.
  • calls[]: {function, span, callee, state, target} where state is function, builtin, plugin or unresolved.

Reference edges never execute anything and grant no capability.

4. Diagnostics

diagnostics[] uses the same stable codes/JSON shape as marqdo check --json. An analysis emitted after a successful check normally has no error diagnostics (warnings may remain).

5. Consumer contract

An independent consumer (Python/Go/JavaScript, without linking Rust crates) must be able to:

  • find a function by id and read its signature/body;
  • find recursive/forward calls and ref edges;
  • map every body node back to source_digest + byte span;
  • reject schema_version it does not understand.

tests/consumers/analysis_consumer.py is one such black-box consumer and crates/cli/tests/analysis_trace.rs runs it when Python is available.

6. Not included

Internal optimization IR, host pointers, plugin handles, proof status and execution results are deliberately absent. Analysis does not claim that a document runs successfully or that any function is proved.