- 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
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_idis a digest of the normalized project root used for this run.lock_digestis a digest ofmarqdo.lock, or""when absent.- Modules are sorted by canonical
id; arrays keep source order. schema_versionis 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,valuewhen present);variable,list,record,member,index;unary(not/neg/pos) andbinary(or,and,eq,ne,lt,le,gt,ge,add,sub,mul,div,floor_div,mod,pow);callwithcalleeandargs;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};resolvedis a module id or null. Imports stay explicit.references[]: Markdown link edges with{source, url, span, state, target_module, target_unit}.stateisresolved,unresolvedorexternal; a failed resolution is never disguised as bound.calls[]:{function, span, callee, state, target}wherestateisfunction,builtin,pluginorunresolved.
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
idand read its signature/body; - find recursive/forward calls and
refedges; - map every body node back to
source_digest+ byte span; - reject
schema_versionit 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.