title

miku-project runtime manifest contract v1

description

Gate G3で承認された、runtime/source artifact、契約互換性、capability、fixture suite、SHA-256のprovenance。

topics

miku-project

cli

runtime

provenance

specification

miku-project runtime manifest contract v1

文書の位置づけ

これはZB-P3.10の成果物であり、Node/Java runtime releaseの互換契約、実行asset、source archive、capability、conformance corpus、由来、SHA-256を一つのmachine-readable manifestへ束縛する。

正本schemaは runtime manifest JSON Schema v1 である。manifestの固定file名はruntime-manifest.jsonとし、Node/Javaの各runtime bundle directoryに一件だけ置く。

目的

版番号の一致だけではruntime互換性を判断しない。次を別々の値として記録し、Agent Skills、shell、CIが人間向けfilenameや「最新版」という推測に頼らず検証できるようにする。

product release version
product / semantic / format / change / CLI contract version
semantic / exchange artifact、result、diagnostic schemaとdiagnostic catalog version
runtime family、役割、runtime version
capability catalog、core profile、provided capability、extension
fixture suite versionとcorpus digest
実行assetとsource archiveの正確なbasename、media type、size、SHA-256
contract sourceとruntime sourceのrepository、revision、tag
Javaが適合対象とした固定Node参照runtimeのversionとmanifest digest

bundle layout

NodeとJavaは別のbundle directoryを持つ。consumerはdirectory内の固定名manifestだけを起点にし、glob、directory走査順、mtime、lexicographicな「最新filename」を使わない。

runtime/node/
├── runtime-manifest.json
├── miku-project-node-1.0.0.mjs
└── miku-project-node-1.0.0-sources.tgz

runtime/java/
├── runtime-manifest.json
├── miku-project-java-1.0.0.jar
└── miku-project-java-1.0.0-sources.tgz

manifestのartifact pathは同じdirectory直下のbasenameだけを許可する。absolute path、separator、.、..、symlinkを許可しない。
artifacts.executableだけを実行する。artifacts.sourcesはreview、license、traceability用であり、fallback実行や動的compileへ使わない。
Node executableはsingle .mjs、Java executableはstandalone fat .jar、sourceは決定論的.tgzを要求する。
manifest、asset、sourceは通常fileでなければならない。

manifestの論理構造

例は次を参照する。

主要fieldの意味は次のとおりである。

field	意味
`product.release_version`	利用者に公開するmiku-project release version。runtime versionとは別値
`product.*_contract_version`	runtimeが実装する承認済み契約version
`product.artifact_schema`	semantic state、Projection、request、diff、plan、approval、provenanceのschema ID `miku_project_artifacts/v1`
`runtime.family`	`node / java`
`runtime.role`	Nodeは`reference`、Javaは`conforming`
`runtime.version`	runtime artifact自身のSemVer
`runtime.launcher`	manifestが指すassetを起動する固定方式。`node`または`java-jar`
`compatibility.capabilities`	catalog既知IDの宣言集合と空extension。schemaは既知subsetを受理し、core profile適合判定が九件のcanonical集合・順序を要求する
`compatibility.conformance`	fixture suite versionと、使用したcorpus全体のdigest
`artifacts.executable`	実際に起動する一fileのbasename、media type、size、digest
`artifacts.sources`	executableへ対応するsource archive
`source.contract`	product contractを得たmiku-project repository revision
`source.runtime`	executable/source archiveをbuildしたrepository revision
`reference_runtime`	Javaが適合したNode manifest。Nodeでは`null`

manifestはbuild timestamp、hostname、absolute build path、runner IDを持たない。同じsource、toolchain、入力から同じartifactを作れる場合、manifest byte列も決定的でなければならない。

versionの関係

product.release_version = 1.0.0とruntime.version = 1.0.0が同じでも、それだけで互換とは判定しない。
product contract、schema、capability profile、fixture suiteの全値がcaller要求と一致し、digest検証が成功して初めて候補runtimeになる。
NodeとJavaのruntime versionは独立して更新できる。Java manifestはreference_runtime.manifest_digestで、適合対象にした固定Node releaseを明示する。
Node manifestのreference_runtimeはnullである。Node runtime自身を再帰参照しない。
source.contract.tagはproduct.release_version、Nodeのsource.runtime.tagはNode runtime version、Javaのsource.runtime.tagはJava runtime versionに対応させる。schemaだけでは値間同値を完全検査できないためrelease validationで照合する。
executable名はNodeでmiku-project-node-<runtime.version>.mjs、Javaでmiku-project-java-<runtime.version>.jar、source名は対応するbasenameのversion部分を共有したmiku-project-<family>-<runtime.version>-sources.tgzとする。JSON Schemaは安全なbasenameと拡張子を検査し、versionとの文字列一致はrelease validationで検査する。

fixture corpus digest

compatibility.conformance.corpus_digestはtestdata/conformance/v1/の内容を次の方法で束縛する。

directory以下の通常fileを再帰列挙し、symlinkと非通常fileを拒否する。
rootからのPOSIX relative pathをUnicode code point昇順に並べる。
各fileのraw byte SHA-256をlowercase hexで計算する。
各fileについて<hex><two spaces><relative-path><LF>をUTF-8で連結する。
連結byte列のSHA-256をcorpus digestとする。

corpus内へcorpus digest fileを置かず、自己参照を避ける。P4/P5でsemantic catalogをmaterializeして内容が変われば、fixture suite versionを維持する場合でもcorpus digestは変わる。release manifestは実際にtestしたdigestだけを記録する。

manifest生成と外側のpin

生成順は次で固定する。

executableとsource archiveを決定論的に生成する。
両fileのsizeとSHA-256を計算する。
conformance corpus digestを計算し、その内容でrelease testを実行する。
source repository revision/tagと全compatibility fieldを入れてmanifestを生成する。
manifestをconformance corpusのcanonical JSON規則でserializeし、末尾LF一件を付ける。
manifest file全体のSHA-256を計算し、Release checksumまたはAgent Skills側のlockへ記録する。

manifest自身へmanifest digestを入れない。manifestが自分自身をhashすると循環するためである。信頼境界は次の二段階になる。

Skills lock / Release checksum
  └─ runtime-manifest.json のSHA-256
       ├─ executableのbasename / size / SHA-256
       ├─ sourcesのbasename / size / SHA-256
       ├─ contract / capability / fixture corpus
       └─ source revision / tag

manifestとartifactを同時に改ざんしてdigestを合わせても、外側でpinしたmanifest digestと一致しないため拒否できる。外側のpinを持たず、manifestの自己申告だけをprovenance検証と呼ばない。

self-validationとconsumer validation

検証責務はruntime自身とconsumerの二層に分ける。

runtime自身はadjacent manifestを起点にschema、version/capability、executable/sourceのpath・size・digestを検査し、project inputを読む前にbundle内部のbindingを確立する。
Agent Skillsやrelease smokeのようにtrust anchorを持つconsumerは、runtime起動前にmanifest raw digestをSkills lockまたはRelease checksumと照合し、起動後にresult bindingも照合する。
direct shell利用者はRelease checksumを配布元から取得して外側で照合できる。照合しない実行はbundle内部の整合性を確認できても、配布元authenticityを証明したことにはならない。

各operation開始前の検証順は次である。

選択policyが指した固定runtime-manifest.jsonを開く。manifest自体が通常fileかつ非symlinkであることを確認する。
trust anchorを持つconsumerは、Skills lockまたはRelease checksumが持つmanifest SHA-256とraw byte digestを比較する。runtime自身はraw digestを計算し、result binding用に保持する。
UTF-8、BOM、JSON duplicate key、runtime manifest schemaを検証する。
product/contract/schema/catalog/capability/fixture suiteがworkflow要求と一致することを確認する。
manifest directoryとbasenameからexecutable/source pathを解決し、directory外へ出ないこと、通常file、非symlink、size一致、family/versionから導出した固定filenameとの一致を確認する。
executableとsourceのSHA-256を毎operation開始前に検証する。
runtime.launcherとartifacts.executable.pathだけからcommandを組み立てる。
CLI resultのruntime bindingが、検証済みmanifestと完全一致することを確認する。

network download、source checkout、package manager、vendor/、PATH上の同名command、runtime directory内の別versionを暗黙利用しない。候補runtimeを変更する場合は新しいmanifest検証として最初から行う。

CLI resultとartifact binding

CLI resultのruntimeは次を持つ。

{
  "binding_status": "verified",
  "family": "node",
  "version": "1.0.0",
  "artifact_digest": { "algorithm": "sha-256", "value": "<64-lowercase-hex>" },
  "manifest_digest": { "algorithm": "sha-256", "value": "<64-lowercase-hex>" },
  "capability_profile": "miku-project-cli-core/v1",
  "fixture_suite_version": "1"
}

verifiedでは上記全fieldを必須かつnon-nullにする。
verifiedはruntime自身がbundle内部のmanifest/asset bindingを検証したことを示す。外部trust anchorによる配布元authenticityまでCLIが自己証明する値ではなく、Agent Skills等のconsumerは外側のmanifest pinとの照合結果を別途成立させる。
manifest/assetを検証できずstructured runtime errorを返す場合だけbinding_status = unverifiedを許可し、digest/profile/fixture fieldは確定できた値またはnullにする。
succeededとdomain/validationによるrejectedは必ずverifiedである。未検証runtimeでprojectを読まない。
output planとprovenanceにもfamily/version/artifact digestに加えmanifest digest、capability profile、fixture suite versionを記録する。approvalはこれらを含むoutput plan digestへ束縛し、runtime bindingを間接的かつ改変不能に束縛する。
plan-change後にmanifest digestが変われば、同じfamily/version/asset digestに見えても別runtime bindingであり、再plan・再承認する。

control operationとworkflow operation

--helpと--versionはembedded metadataだけで応答できるcontrol operationとし、manifest欠落時にも診断目的で利用できる。五つのworkflow commandはproject inputを読む前にmanifest/executable/capability bindingを検証する。

invocation grammarを確定できないcli usage errorはunverifiedを許可する。workflow commandを確定できた後のusage errorはmanifestを検証してverifiedで返すことを基本とする。ただしmanifest自体が不正ならusage errorよりruntime.manifest-invalidを優先し、project inputやdestinationへ触れない。

failure mapping

condition	diagnostic	status / exit	副作用
manifest missing、JSON/schema/field不整合、未知capability ID、path escape	`runtime.manifest-invalid`	runtime-error / 3	project input未読、destinationなし
executableのsize/digest不一致	`runtime.artifact-digest-mismatch`	runtime-error / 3	同上
core capability不足、canonical順不一致、fixture/profile要求不一致	`runtime.capability-missing`	runtime-error / 3	同上
source archive不在・size/digest不一致	`runtime.manifest-invalid`	runtime-error / 3	release/Skillsでは起動しない
manifestは有効だがdestination filesystemがprotocol非対応	`publication.capability-unsupported`	rejected / 1	output plan/committed artifactなし

source archiveは実行に不要だが、v1 release bundleのprovenance必須memberである。Skillsが意図的にsourceを同梱しない軽量bundleを将来設ける場合は、上流release manifestをそのまま書き換えず、別のbundle lockが「runtime assetだけを受領した」ことを表現する。

Navigation Menu

miku-project runtime manifest contract v1

文書の位置づけ

目的

bundle layout

manifestの論理構造

versionの関係

fixture corpus digest

manifest生成と外側のpin

self-validationとconsumer validation

CLI resultとartifact binding

control operationとworkflow operation

failure mapping

P3.10 review checklist

FilesExpand file tree

miku-project-runtime-manifest-contract-v1.md

Latest commit

History

miku-project-runtime-manifest-contract-v1.md

File metadata and controls

miku-project runtime manifest contract v1

文書の位置づけ

目的

bundle layout

manifestの論理構造

versionの関係

fixture corpus digest

manifest生成と外側のpin

self-validationとconsumer validation

CLI resultとartifact binding

control operationとworkflow operation

failure mapping

P3.10 review checklist