@hardkas/core 0.8.20-alpha → 0.9.1-alpha

package/README.md

@@ -1,48 +1,56 @@
-# `@hardkas/core`
-
-The Core package provides the foundational safety rails, filesystem abstractions, and atomic persistence primitives for the entire HardKAS ecosystem.
-
-## 1. Atomic Persistence Variants
-
-All state mutation in HardKAS relies on strict atomic persistence to prevent corruption during unexpected crashes or power loss. The standard flow follows the `temp + rename + fsync` pattern.
-
-### Flow: Standard Atomic Write
-1. Data is written to a temporary file (`.hardkas/tmp/<uuid>.json`).
-2. `fs.fsyncSync()` is called on the temporary file to flush buffers to disk.
-3. The temporary file is atomically renamed over the target file (e.g., `state.json`).
-4. `fs.fsyncSync()` is called on the **parent directory** (`.hardkas/`) to ensure the directory entry is durably linked.
-
-### Variant: Fallback Write
-If the filesystem does not support directory `fsync` (e.g., certain Windows/WSL configurations), the engine catches `EINVAL` or `EISDIR` and gracefully degrades to a standard atomic rename without the parent directory flush, logging a warning to the telemetry stream.
-
-## 2. Workspace Lock Mechanisms
-
-To prevent concurrent modifications to the developer workspace, `@hardkas/core` uses a conservative file-based locking strategy (`.hardkas/locks/<domain>.lock`).
-
-### Flow: Lock Acquisition
-1. Process attempts to create a lock file using `fs.openSync(path, 'wx')` (exclusive write).
-2. If successful, the process PID and timestamp are written.
-3. If `EEXIST` is thrown, the process enters a **spin-wait loop** with exponential backoff (up to 30 seconds).
-
-### Variant: Stale Lock Detection & Recovery (LockHell Defense)
-If a lock cannot be acquired after 30 seconds, the engine checks if the holding process is still alive.
-- **Dead Process:** If `process.kill(pid, 0)` fails (indicating the PID no longer exists), the lock is deemed **stale**. The engine atomically overrides the lock and logs a `STALE_LOCK_RECOVERY` telemetry event.
-- **Live Process:** If the PID is active, HardKAS strictly aborts with `HARDKAS_LOCK_CONTENTION`. It will *never* violently break a lock held by a live process.
-- **Zero-Byte Locks:** If a system crash occurs precisely when the `wx` descriptor is created but before the PID is written (a TOCTOU scenario), HardKAS considers any 0-byte lock older than 10 seconds as implicitly stale.
-
-## 3. AppendCoordinator (Event Ledger)
-
-The `events.jsonl` ledger is the source of truth for the workspace. It is strictly append-only.
-
-### Flow: Ledger Append
-1. Acquire the exclusive `events` lock.
-2. Read the tail of the stream to determine the last `eventId`.
-3. Append the new JSON payload with a trailing newline.
-4. `fs.fsyncSync()` the file descriptor.
-
-### Variant: Tail Corruption Repair
-If the chaos engine (or a crash) leaves a partial JSON object at the tail of `events.jsonl` (e.g., `{"eventId": 142, "domain": "tx"` missing the closing brace):
-1. The `AppendCoordinator` detects `Unexpected end of JSON input` during tail-read.
-2. It explicitly scans backward to find the last valid newline boundary.
-3. The corrupted tail is truncated automatically.
-4. A `CORRUPT_TAIL_RECOVERY` event is dispatched to `telemetry.jsonl`.
+# `@hardkas/core`
+
+The Core package provides the foundational safety rails, filesystem abstractions, and atomic persistence primitives for the entire HardKAS ecosystem.
+
+## 1. Atomic Persistence Variants
+
+All state mutation in HardKAS relies on strict atomic persistence to prevent corruption during unexpected crashes or power loss. The standard flow follows the `temp + rename + fsync` pattern.
+
+### Flow: Standard Atomic Write
+
+1. Data is written to a temporary file (`.hardkas/tmp/<uuid>.json`).
+2. `fs.fsyncSync()` is called on the temporary file to flush buffers to disk.
+3. The temporary file is atomically renamed over the target file (e.g., `state.json`).
+4. `fs.fsyncSync()` is called on the **parent directory** (`.hardkas/`) to ensure the directory entry is durably linked.
+
+### Variant: Fallback Write
+
+If the filesystem does not support directory `fsync` (e.g., certain Windows/WSL configurations), the engine catches `EINVAL` or `EISDIR` and gracefully degrades to a standard atomic rename without the parent directory flush, logging a warning to the telemetry stream.
+
+## 2. Workspace Lock Mechanisms
+
+To prevent concurrent modifications to the developer workspace, `@hardkas/core` uses a conservative file-based locking strategy (`.hardkas/locks/<domain>.lock`).
+
+### Flow: Lock Acquisition
+
+1. Process attempts to create a lock file using `fs.openSync(path, 'wx')` (exclusive write).
+2. If successful, the process PID and timestamp are written.
+3. If `EEXIST` is thrown, the process enters a **spin-wait loop** with exponential backoff (up to 30 seconds).
+
+### Variant: Stale Lock Detection & Recovery (LockHell Defense)
+
+If a lock cannot be acquired after 30 seconds, the engine checks if the holding process is still alive.
+
+- **Dead Process:** If `process.kill(pid, 0)` fails (indicating the PID no longer exists), the lock is deemed **stale**. The engine atomically overrides the lock and logs a `STALE_LOCK_RECOVERY` telemetry event.
+- **Live Process:** If the PID is active, HardKAS strictly aborts with `HARDKAS_LOCK_CONTENTION`. It will _never_ violently break a lock held by a live process.
+- **Zero-Byte Locks:** If a system crash occurs precisely when the `wx` descriptor is created but before the PID is written (a TOCTOU scenario), HardKAS considers any 0-byte lock older than 10 seconds as implicitly stale.
+
+## 3. AppendCoordinator (Event Ledger)
+
+The `events.jsonl` ledger is the source of truth for the workspace. It is strictly append-only.
+
+### Flow: Ledger Append
+
+1. Acquire the exclusive `events` lock.
+2. Read the tail of the stream to determine the last `eventId`.
+3. Append the new JSON payload with a trailing newline.
+4. `fs.fsyncSync()` the file descriptor.
+
+### Variant: Tail Corruption Repair
+
+If the chaos engine (or a crash) leaves a partial JSON object at the tail of `events.jsonl` (e.g., `{"eventId": 142, "domain": "tx"` missing the closing brace):
+
+1. The `AppendCoordinator` detects `Unexpected end of JSON input` during tail-read.
+2. It explicitly scans backward to find the last valid newline boundary.
+3. The corrupted tail is truncated automatically.
+4. A `CORRUPT_TAIL_RECOVERY` event is dispatched to `telemetry.jsonl`.

package/dist/index.d.ts

@@ -75,6 +75,268 @@ declare const asNetworkId: <T extends string>(id: T) => Brand<T, "NetworkId">;
 declare const asEventSequence: (seq: number) => EventSequence;
 declare const asDaaScore: (score: number | bigint) => DaaScore;
 
+/**
+ * Parses a KAS decimal string (e.g. "1.234") into Sompi (bigint).
+ * If a bigint is provided, it is assumed to be an already-parsed sompi amount.
+ *
+ * Rules:
+ * - string input = decimal KAS
+ * - bigint input = already sompi
+ * - format input = sompi
+ * - no floats
+ * - no Number decimal
+ * - no silent rounding
+ *
+ * @param input The KAS amount as a decimal string, or sompi as a bigint.
+ * @returns The sompi amount as a bigint.
+ */
+declare function parseKasToSompi(input: string | bigint | number): bigint;
+/**
+ * Formats a sompi amount into a KAS decimal string.
+ * @param sompi The sompi amount as a bigint or string representation of a bigint.
+ * @returns The KAS amount as a string.
+ */
+declare function formatSompiToKas(sompi: bigint | string): string;
+/**
+ * Formats a signed sompi amount into a KAS decimal string.
+ * This is meant ONLY for reporting deltas, audit statements, or rendering logic.
+ * It is NOT intended for validating spendable balances or user input amounts.
+ * @param sompi The sompi amount as a signed bigint or string representation of a bigint.
+ * @returns The KAS amount as a string (with a leading '-' if negative).
+ */
+declare function formatSignedSompiToKas(sompi: bigint | string): string;
+
+interface SchemaMetadata {
+    type: string;
+    domain: "tx" | "silver" | "zk" | "vprogs" | "programmability" | "corpus" | "infra" | "cli" | "audit";
+    version: "v1" | "v2" | "legacy" | string;
+    stability: "stable" | "stable-local" | "experimental" | "fixture-coherence" | "inspect-only" | "report";
+    legacy?: boolean;
+}
+declare const HardkasSchemas: {
+    readonly Event: "hardkas.event";
+    readonly WorkflowIntent: "hardkas.workflow.intent";
+    readonly TxPlan: "hardkas.txPlan";
+    readonly TxPlanV1: "hardkas.txPlan.v1";
+    readonly TxPlanV2: "hardkas.txPlan.v2";
+    readonly SignedTx: "hardkas.signedTx";
+    readonly SignedTxV1: "hardkas.signedTx.v1";
+    readonly TxReceipt: "hardkas.txReceipt";
+    readonly TxReceiptV1: "hardkas.txReceipt.v1";
+    readonly TxTrace: "hardkas.txTrace";
+    readonly TxTraceV1: "hardkas.txTrace.v1";
+    readonly Snapshot: "hardkas.snapshot";
+    readonly SnapshotV1: "hardkas.snapshot.v1";
+    readonly WorkflowV1: "hardkas.workflow.v1";
+    readonly PolicyV1: "hardkas.policy.v1";
+    readonly AssumptionV1: "hardkas.assumption.v1";
+    readonly NetworkProfileV1: "hardkas.networkProfile.v1";
+    readonly MigrationReceiptV1: "hardkas.migrationReceipt.v1";
+    readonly ErrorV1: "hardkas.error.v1";
+    readonly ReplayV1: "hardkas.replay.v1";
+    readonly ReplayDiffV1: "hardkas.replayDiff.v1";
+    readonly ReplayReportV1: "hardkas.replayReport.v1";
+    readonly ReplayVerifyV1: "hardkas.replayVerify.v1";
+    readonly LocalnetStateV1: "hardkas.localnetState.v1";
+    readonly LocalnetStatusV1: "hardkas.localnetStatus.v1";
+    readonly LocalnetControlV1: "hardkas.localnetControl.v1";
+    readonly LocalnetFundingV1: "hardkas.localnetFunding.v1";
+    readonly RealAccountStoreV1: "hardkas.realAccountStore.v1";
+    readonly EncryptedKeystoreV2: "hardkas.encryptedKeystore.v2";
+    readonly NodeStatusV1: "hardkas.nodeStatus.v1";
+    readonly DeploymentV1: "hardkas.deployment.v1";
+    readonly DeploymentIndexV1: "hardkas.deploymentIndex.v1";
+    readonly IgraTxPlan: "hardkas.igraTxPlan";
+    readonly IgraTxPlanV1: "hardkas.igraTxPlan.v1";
+    readonly IgraSignedTxV1: "hardkas.igraSignedTx.v1";
+    readonly IgraTxReceipt: "hardkas.igraTxReceipt";
+    readonly IgraTxReceiptV1: "hardkas.igraTxReceipt.v1";
+    readonly L2ProfileV1: "hardkas.l2Profile.v1";
+    readonly L2BridgeAssumptionsV1: "hardkas.l2BridgeAssumptions.v1";
+    readonly SilverCompile: "hardkas.silver.compile";
+    readonly SilverTest: "hardkas.silver.test";
+    readonly SilverDeployPlan: "hardkas.silver.deployPlan";
+    readonly SilverDeploy: "hardkas.silver.deploy";
+    readonly SilverSpendPlan: "hardkas.silver.spendPlan";
+    readonly SilverSpendReceipt: "hardkas.silver.spendReceipt";
+    readonly SilverDeploySimulation: "hardkas.silver.deploySimulation";
+    readonly SilverSpendSimulation: "hardkas.silver.spendSimulation";
+    readonly SilverSimulationStateV1: "hardkas.silver.simulationState.v1";
+    readonly ProgrammabilityCapabilitiesV1: "hardkas.programmability.capabilities.v1";
+    readonly ProgrammabilityInspectV1: "hardkas.programmability.inspect.v1";
+    readonly ProgrammabilityVerifyV1: "hardkas.programmability.verify.v1";
+    readonly ProgrammabilityCorpusReportV1: "hardkas.programmability.corpusReport.v1";
+    readonly ProgrammabilityAppPlanV1: "hardkas.programmability.appPlan.v1";
+    readonly ProgrammabilitySurfaceCheckV1: "hardkas.programmability.surfaceCheck.v1";
+    readonly ProgrammabilityExamplesCheckV1: "hardkas.programmability.examplesCheck.v1";
+    readonly ProgrammabilityTemplatesCheckV1: "hardkas.programmability.templatesCheck.v1";
+    readonly ZkCapabilitiesV1: "hardkas.zkCapabilities.v1";
+    readonly ZkCorpusV1: "hardkas.zkCorpus.v1";
+    readonly ZkProofInspectV1: "hardkas.zkProofInspect.v1";
+    readonly ZkProofVerificationV1: "hardkas.zkProofVerification.v1";
+    readonly ZkCorpusVerificationV1: "hardkas.zkCorpusVerification.v1";
+    readonly ZkGroth16FixtureV1: "hardkas.zkGroth16Fixture.v1";
+    readonly ZkRisc0FixtureV1: "hardkas.zkRisc0Fixture.v1";
+    readonly ZkGroth16ProofV1: "hardkas.zk.groth16.proof.v1";
+    readonly ZkGroth16PublicInputsV1: "hardkas.zk.groth16.publicInputs.v1";
+    readonly ZkGroth16VerificationKeyV1: "hardkas.zk.groth16.verificationKey.v1";
+    readonly ZkGroth16VerifierMetadataV1: "hardkas.zk.groth16.verifierMetadata.v1";
+    readonly ZkGroth16VerifyReportV1: "hardkas.zk.groth16.verifyReport.v1";
+    readonly ZkRisc0ImageIdV1: "hardkas.zk.risc0.imageId.v1";
+    readonly ZkRisc0JournalV1: "hardkas.zk.risc0.journal.v1";
+    readonly ZkRisc0ReceiptV1: "hardkas.zk.risc0.receipt.v1";
+    readonly ZkRisc0VerifyReportV1: "hardkas.zk.risc0.verifyReport.v1";
+    readonly VProgsCapabilitiesV1: "hardkas.vprogsCapabilities.v1";
+    readonly VProgsInspectV1: "hardkas.vprogsInspect.v1";
+    readonly VProgsStatusV1: "hardkas.vprogsStatus.v1";
+    readonly VProgsInspectFixtureV1: "hardkas.vprogs.inspectFixture.v1";
+    readonly ToccataProgrammabilityCorpusV1: "hardkas.toccataProgrammabilityCorpus.v1";
+    readonly ToccataGauntletV1: "hardkas.toccataGauntlet.v1";
+    readonly ToccataCorpusV1: "hardkas.toccataCorpus.v1";
+    readonly ToccataGoldenCompareV1: "hardkas.toccataGoldenCompare.v1";
+    readonly ToccataGoldenFailureCaseV1: "hardkas.toccataGoldenFailureCase.v1";
+    readonly ToccataGoldenManifestV1: "hardkas.toccataGoldenManifest.v1";
+    readonly ToccataGoldenFailureManifestV1: "hardkas.toccataGoldenFailureManifest.v1";
+    readonly PostReleaseProbe: "hardkas.postReleaseProbe";
+    readonly CliReferenceV1: "hardkas.cliReference.v1";
+    readonly ArtifactV1: "hardkas.artifact.v1";
+    readonly ArtifactInspectV1: "hardkas.artifactInspect.v1";
+    readonly AuditV1: "hardkas.audit.v1";
+    readonly PostReleaseBreakGauntletV1: "hardkas.postReleaseBreakGauntlet.v1";
+    readonly KaspaDoctorV1: "hardkas.kaspaDoctor.v1";
+    readonly DevDoctorV1: "hardkas.devDoctor.v1";
+    readonly DevServerV1: "hardkas.devServer.v1";
+    readonly LocalWizardV1: "hardkas.localWizard.v1";
+    readonly QueryRebuildV1: "hardkas.queryRebuild.v1";
+    readonly QueryVerifyV1: "hardkas.queryVerify.v1";
+    readonly SemanticBundleV1: "hardkas.semantic-bundle.v1";
+    readonly SessionV1: "hardkas.session.v1";
+    readonly SessionV0: "hardkas.session.v0";
+    readonly TelemetryV1: "hardkas.telemetry.v1";
+    readonly TortureReportV1: "hardkas.tortureReport.v1";
+    readonly PruneReportV1: "hardkas.pruneReport.v1";
+    readonly LockV1: "hardkas.lock.v1";
+    readonly BridgeLocalPlanV1: "hardkas.bridge.localPlan.v1";
+    readonly BridgeLocalSimulationV1: "hardkas.bridge.localSimulation.v1";
+    readonly KaswareLocalV1: "hardkas.kaswareLocal.v1";
+    readonly MetamaskLocalV1: "hardkas.metamaskLocal.v1";
+    readonly ExampleDocumentAnchorV1: "hardkas.example.documentAnchor.v1";
+};
+type HardkasSchema = typeof HardkasSchemas[keyof typeof HardkasSchemas];
+/** Alias for compatibility */
+declare const ArtifactTypes: {
+    readonly Event: "hardkas.event";
+    readonly WorkflowIntent: "hardkas.workflow.intent";
+    readonly TxPlan: "hardkas.txPlan";
+    readonly TxPlanV1: "hardkas.txPlan.v1";
+    readonly TxPlanV2: "hardkas.txPlan.v2";
+    readonly SignedTx: "hardkas.signedTx";
+    readonly SignedTxV1: "hardkas.signedTx.v1";
+    readonly TxReceipt: "hardkas.txReceipt";
+    readonly TxReceiptV1: "hardkas.txReceipt.v1";
+    readonly TxTrace: "hardkas.txTrace";
+    readonly TxTraceV1: "hardkas.txTrace.v1";
+    readonly Snapshot: "hardkas.snapshot";
+    readonly SnapshotV1: "hardkas.snapshot.v1";
+    readonly WorkflowV1: "hardkas.workflow.v1";
+    readonly PolicyV1: "hardkas.policy.v1";
+    readonly AssumptionV1: "hardkas.assumption.v1";
+    readonly NetworkProfileV1: "hardkas.networkProfile.v1";
+    readonly MigrationReceiptV1: "hardkas.migrationReceipt.v1";
+    readonly ErrorV1: "hardkas.error.v1";
+    readonly ReplayV1: "hardkas.replay.v1";
+    readonly ReplayDiffV1: "hardkas.replayDiff.v1";
+    readonly ReplayReportV1: "hardkas.replayReport.v1";
+    readonly ReplayVerifyV1: "hardkas.replayVerify.v1";
+    readonly LocalnetStateV1: "hardkas.localnetState.v1";
+    readonly LocalnetStatusV1: "hardkas.localnetStatus.v1";
+    readonly LocalnetControlV1: "hardkas.localnetControl.v1";
+    readonly LocalnetFundingV1: "hardkas.localnetFunding.v1";
+    readonly RealAccountStoreV1: "hardkas.realAccountStore.v1";
+    readonly EncryptedKeystoreV2: "hardkas.encryptedKeystore.v2";
+    readonly NodeStatusV1: "hardkas.nodeStatus.v1";
+    readonly DeploymentV1: "hardkas.deployment.v1";
+    readonly DeploymentIndexV1: "hardkas.deploymentIndex.v1";
+    readonly IgraTxPlan: "hardkas.igraTxPlan";
+    readonly IgraTxPlanV1: "hardkas.igraTxPlan.v1";
+    readonly IgraSignedTxV1: "hardkas.igraSignedTx.v1";
+    readonly IgraTxReceipt: "hardkas.igraTxReceipt";
+    readonly IgraTxReceiptV1: "hardkas.igraTxReceipt.v1";
+    readonly L2ProfileV1: "hardkas.l2Profile.v1";
+    readonly L2BridgeAssumptionsV1: "hardkas.l2BridgeAssumptions.v1";
+    readonly SilverCompile: "hardkas.silver.compile";
+    readonly SilverTest: "hardkas.silver.test";
+    readonly SilverDeployPlan: "hardkas.silver.deployPlan";
+    readonly SilverDeploy: "hardkas.silver.deploy";
+    readonly SilverSpendPlan: "hardkas.silver.spendPlan";
+    readonly SilverSpendReceipt: "hardkas.silver.spendReceipt";
+    readonly SilverDeploySimulation: "hardkas.silver.deploySimulation";
+    readonly SilverSpendSimulation: "hardkas.silver.spendSimulation";
+    readonly SilverSimulationStateV1: "hardkas.silver.simulationState.v1";
+    readonly ProgrammabilityCapabilitiesV1: "hardkas.programmability.capabilities.v1";
+    readonly ProgrammabilityInspectV1: "hardkas.programmability.inspect.v1";
+    readonly ProgrammabilityVerifyV1: "hardkas.programmability.verify.v1";
+    readonly ProgrammabilityCorpusReportV1: "hardkas.programmability.corpusReport.v1";
+    readonly ProgrammabilityAppPlanV1: "hardkas.programmability.appPlan.v1";
+    readonly ProgrammabilitySurfaceCheckV1: "hardkas.programmability.surfaceCheck.v1";
+    readonly ProgrammabilityExamplesCheckV1: "hardkas.programmability.examplesCheck.v1";
+    readonly ProgrammabilityTemplatesCheckV1: "hardkas.programmability.templatesCheck.v1";
+    readonly ZkCapabilitiesV1: "hardkas.zkCapabilities.v1";
+    readonly ZkCorpusV1: "hardkas.zkCorpus.v1";
+    readonly ZkProofInspectV1: "hardkas.zkProofInspect.v1";
+    readonly ZkProofVerificationV1: "hardkas.zkProofVerification.v1";
+    readonly ZkCorpusVerificationV1: "hardkas.zkCorpusVerification.v1";
+    readonly ZkGroth16FixtureV1: "hardkas.zkGroth16Fixture.v1";
+    readonly ZkRisc0FixtureV1: "hardkas.zkRisc0Fixture.v1";
+    readonly ZkGroth16ProofV1: "hardkas.zk.groth16.proof.v1";
+    readonly ZkGroth16PublicInputsV1: "hardkas.zk.groth16.publicInputs.v1";
+    readonly ZkGroth16VerificationKeyV1: "hardkas.zk.groth16.verificationKey.v1";
+    readonly ZkGroth16VerifierMetadataV1: "hardkas.zk.groth16.verifierMetadata.v1";
+    readonly ZkGroth16VerifyReportV1: "hardkas.zk.groth16.verifyReport.v1";
+    readonly ZkRisc0ImageIdV1: "hardkas.zk.risc0.imageId.v1";
+    readonly ZkRisc0JournalV1: "hardkas.zk.risc0.journal.v1";
+    readonly ZkRisc0ReceiptV1: "hardkas.zk.risc0.receipt.v1";
+    readonly ZkRisc0VerifyReportV1: "hardkas.zk.risc0.verifyReport.v1";
+    readonly VProgsCapabilitiesV1: "hardkas.vprogsCapabilities.v1";
+    readonly VProgsInspectV1: "hardkas.vprogsInspect.v1";
+    readonly VProgsStatusV1: "hardkas.vprogsStatus.v1";
+    readonly VProgsInspectFixtureV1: "hardkas.vprogs.inspectFixture.v1";
+    readonly ToccataProgrammabilityCorpusV1: "hardkas.toccataProgrammabilityCorpus.v1";
+    readonly ToccataGauntletV1: "hardkas.toccataGauntlet.v1";
+    readonly ToccataCorpusV1: "hardkas.toccataCorpus.v1";
+    readonly ToccataGoldenCompareV1: "hardkas.toccataGoldenCompare.v1";
+    readonly ToccataGoldenFailureCaseV1: "hardkas.toccataGoldenFailureCase.v1";
+    readonly ToccataGoldenManifestV1: "hardkas.toccataGoldenManifest.v1";
+    readonly ToccataGoldenFailureManifestV1: "hardkas.toccataGoldenFailureManifest.v1";
+    readonly PostReleaseProbe: "hardkas.postReleaseProbe";
+    readonly CliReferenceV1: "hardkas.cliReference.v1";
+    readonly ArtifactV1: "hardkas.artifact.v1";
+    readonly ArtifactInspectV1: "hardkas.artifactInspect.v1";
+    readonly AuditV1: "hardkas.audit.v1";
+    readonly PostReleaseBreakGauntletV1: "hardkas.postReleaseBreakGauntlet.v1";
+    readonly KaspaDoctorV1: "hardkas.kaspaDoctor.v1";
+    readonly DevDoctorV1: "hardkas.devDoctor.v1";
+    readonly DevServerV1: "hardkas.devServer.v1";
+    readonly LocalWizardV1: "hardkas.localWizard.v1";
+    readonly QueryRebuildV1: "hardkas.queryRebuild.v1";
+    readonly QueryVerifyV1: "hardkas.queryVerify.v1";
+    readonly SemanticBundleV1: "hardkas.semantic-bundle.v1";
+    readonly SessionV1: "hardkas.session.v1";
+    readonly SessionV0: "hardkas.session.v0";
+    readonly TelemetryV1: "hardkas.telemetry.v1";
+    readonly TortureReportV1: "hardkas.tortureReport.v1";
+    readonly PruneReportV1: "hardkas.pruneReport.v1";
+    readonly LockV1: "hardkas.lock.v1";
+    readonly BridgeLocalPlanV1: "hardkas.bridge.localPlan.v1";
+    readonly BridgeLocalSimulationV1: "hardkas.bridge.localSimulation.v1";
+    readonly KaswareLocalV1: "hardkas.kaswareLocal.v1";
+    readonly MetamaskLocalV1: "hardkas.metamaskLocal.v1";
+    readonly ExampleDocumentAnchorV1: "hardkas.example.documentAnchor.v1";
+};
+declare function isKnownArtifactType(type: string): type is HardkasSchema;
+declare function assertKnownArtifactType(type: string): HardkasSchema;
+declare function describeArtifactType(type: HardkasSchema): SchemaMetadata;
+
 /**
  * HardKAS Core Event Domains.
  */
@@ -254,7 +516,7 @@ interface EventPayloadByKind {
  * Standardizes how events are captured and tracked across the system.
  */
 interface EventEnvelope<K extends EventKind = EventKind> {
-    schema: "hardkas.event";
+    schema: typeof HardkasSchemas.Event;
     version: "1.0.0";
     eventId: EventId;
     domain: EventDomain;
@@ -434,7 +696,7 @@ interface StateProvenance {
  * HardKAS Lock Metadata schema v1
  */
 interface LockMetadata {
-    schema: "hardkas.lock.v1";
+    schema: typeof HardkasSchemas.LockV1;
     name: string;
     pid: number;
     command: string;
@@ -527,7 +789,7 @@ interface RuntimeNoiseDiff {
     metadataDrift: string[];
 }
 interface LayeredReplayDiff {
-    schema: "hardkas.replayDiff.v1";
+    schema: typeof HardkasSchemas.ReplayDiffV1;
     structural: StructuralDiff;
     deterministic: DeterministicDiff;
     observational: RuntimeNoiseDiff;
@@ -793,7 +1055,7 @@ declare class AppendCoordinator {
     };
 }
 
-declare const CURRENT_RUNTIME_VERSION = "0.8.20-alpha";
+declare const CURRENT_RUNTIME_VERSION = "0.9.1-alpha";
 declare const MIN_SUPPORTED_VERSION = "0.5.0-alpha";
 interface MigrationStatus {
     needsMigration: boolean;
@@ -808,16 +1070,47 @@ declare class MigrationManager {
     private static compareSemver;
 }
 
+/**
+ * Calculates the Blake2b 32-byte hash of the raw redeem script bytes.
+ * This MUST ONLY be the raw bytes, never the artifact JSON or wrapper hex.
+ *
+ * @param scriptHexOrBytes The compiled script hex string or Buffer
+ * @returns 32-byte hash as hex string
+ */
+declare function createRedeemScriptHash(scriptHexOrBytes: string | Buffer | Uint8Array): string;
+/**
+ * Creates a Kaspa standard P2SH locking script (BIP16-like but with Blake2b).
+ * Version is always 0 for standard script hashes in Kaspa currently,
+ * although future VM versions might use 8.
+ *
+ * @param scriptHexOrBytes The compiled script hex string or Buffer
+ */
+declare function createKaspaP2shBlake2bLock(scriptHexOrBytes: string | Buffer | Uint8Array): {
+    scriptPublicKeyVersion: number;
+    lockingScriptHex: string;
+    redeemScriptHash: string;
+    redeemScriptHex: string;
+};
+/**
+ * Creates a valid Kaspa v2.0.0 signature script for a P2SH UTXO.
+ * The signature script must be push-only. It pushes any arguments,
+ * followed by the raw redeem script itself.
+ *
+ * @param args Array of hex strings representing the arguments to push
+ * @param redeemScriptHex The compiled script hex string
+ */
+declare function createPushOnlySignatureScript(args: string[], redeemScriptHex: string): string;
+
 declare const SOMPI_PER_KAS = 100000000n;
 declare const kaspaNetworkIdSchema: z.ZodEnum<["mainnet", "testnet-10", "testnet-11", "testnet-12", "simnet", "simnet-1", "devnet", "simulated", "igra"]>;
 type NetworkId = Brand<z.infer<typeof kaspaNetworkIdSchema>, "NetworkId">;
 declare const executionModeSchema: z.ZodEnum<["simulated", "real", "readonly"]>;
 type ExecutionMode = z.infer<typeof executionModeSchema>;
-declare const artifactTypeSchema: z.ZodEnum<["txPlan", "signedTx", "txReceipt", "txTrace", "snapshot", "workflow.v1", "policy.v1", "networkProfile.v1", "assumption.v1", "migrationReceipt.v1"]>;
+declare const artifactTypeSchema: z.ZodEnum<["txPlan", "signedTx", "txReceipt", "txTrace", "snapshot", "workflow.v1", "policy.v1", "networkProfile.v1", "assumption.v1", "migrationReceipt.v1", "silver.compile", "silver.test", "silver.spendPlan", "silver.deployPlan", "silver.deploy", "silver.spendReceipt", "silver.deploySimulation", "silver.spendSimulation"]>;
 type ArtifactType = z.infer<typeof artifactTypeSchema>;
 declare const NetworkIdSchema: z.ZodEnum<["mainnet", "testnet-10", "testnet-11", "testnet-12", "simnet", "simnet-1", "devnet", "simulated", "igra"]>;
 declare const ExecutionModeSchema: z.ZodEnum<["simulated", "real", "readonly"]>;
-declare const ArtifactTypeSchema: z.ZodEnum<["txPlan", "signedTx", "txReceipt", "txTrace", "snapshot", "workflow.v1", "policy.v1", "networkProfile.v1", "assumption.v1", "migrationReceipt.v1"]>;
+declare const ArtifactTypeSchema: z.ZodEnum<["txPlan", "signedTx", "txReceipt", "txTrace", "snapshot", "workflow.v1", "policy.v1", "networkProfile.v1", "assumption.v1", "migrationReceipt.v1", "silver.compile", "silver.test", "silver.spendPlan", "silver.deployPlan", "silver.deploy", "silver.spendReceipt", "silver.deploySimulation", "silver.spendSimulation"]>;
 declare const hardkasConfigSchema: z.ZodObject<{
     project: z.ZodObject<{
         name: z.ZodString;
@@ -895,7 +1188,5 @@ declare class InvariantViolationError extends HardkasError {
     });
 }
 declare function parseHardkasConfig(input: unknown): HardkasConfig;
-declare function parseKasToSompi(input: string): bigint;
-declare function formatSompi(amountSompi: bigint): string;
 
-export { type AcquireLockArgs, type AnomalyEvent, type AnomalyType, AppendCoordinator, type ArtifactId, type ArtifactStatus, type ArtifactType, ArtifactTypeSchema, type Brand, type Branded, CURRENT_RUNTIME_VERSION, type ContentHash, type CoreEvent, type CoreEventListener, type CorrelationId, type CorruptionCode, type CorruptionIssue, type CorruptionSeverity, type CreateSnapshotOptions, type DaaScore, type DeterministicClock, type DeterministicDiff, type DeterministicRandom, EnvironmentTelemetry, type EventDomain, type EventEnvelope, type EventId, type EventKind, type EventPayloadByKind, type EventSequence, type ExecutionMode, ExecutionModeSchema, type HardkasConfig, HardkasError, type IdProvider, type IntegrityStatus, type InvariantDomain, type InvariantSeverity, InvariantViolationError, type KaspaAddress, LOCK_ORDER, type LayeredReplayDiff, type LineageId, type LockHandle, type LockMetadata, MIN_SUPPORTED_VERSION, MigrationManager, type MigrationResult, type MigrationStatus, type NetworkId, NetworkIdSchema, type ReplayContext, type RotationResult, type RpcEndpointId, type RuntimeContext, type RuntimeNoiseDiff, SOMPI_PER_KAS, type SchemaVersion, type SemanticDriftReport, type SemanticIdentity, type Severity, type SnapshotManifest, type StampedEvent, type StateProvenance, type StructuralDiff, TelemetryManager, TelemetryRotator, type TelemetrySubsystem, type TxId, type UnknownEventPayload, type WorkflowId, type WriteFileAtomicOptions, acquireLock, artifactTypeSchema, asArtifactId, asContentHash, asCorrelationId, asDaaScore, asEventId, asEventSequence, asKaspaAddress, asLineageId, asNetworkId, asRpcEndpointId, asTxId, asWorkflowId, assertNoSemanticDrift, attachLedgerAppender, classifyArtifactStatus, clearLock, comparePrePostMigrationLineage, coreEvents, createEventEnvelope, createSnapshot, detectSemanticDrift, deterministicCompare, diffReplays, executionModeSchema, formatCorruptionIssue, formatSompi, getTelemetry, globalTelemetry, hardkasConfigSchema, isProcessAlive, kaspaNetworkIdSchema, listLocks, maskSecrets, migrateArtifact, parseHardkasConfig, parseKasToSompi, readSnapshotManifest, redactSecret, resolveCanonicalArtifact, resolveLineage, systemRuntimeContext, telemetryContextStorage, validateEventEnvelope, validateStatusTransition, verifyArtifactIntegrity, verifyCapabilityBoundary, verifyMigrationIntegrity, verifyProjectionFreshness, verifyReplay, withLock, withLocks, writeFileAtomic, writeFileAtomicSync };
+export { type AcquireLockArgs, type AnomalyEvent, type AnomalyType, AppendCoordinator, type ArtifactId, type ArtifactStatus, type ArtifactType, ArtifactTypeSchema, ArtifactTypes, type Brand, type Branded, CURRENT_RUNTIME_VERSION, type ContentHash, type CoreEvent, type CoreEventListener, type CorrelationId, type CorruptionCode, type CorruptionIssue, type CorruptionSeverity, type CreateSnapshotOptions, type DaaScore, type DeterministicClock, type DeterministicDiff, type DeterministicRandom, EnvironmentTelemetry, type EventDomain, type EventEnvelope, type EventId, type EventKind, type EventPayloadByKind, type EventSequence, type ExecutionMode, ExecutionModeSchema, type HardkasConfig, HardkasError, type HardkasSchema, HardkasSchemas, type IdProvider, type IntegrityStatus, type InvariantDomain, type InvariantSeverity, InvariantViolationError, type KaspaAddress, LOCK_ORDER, type LayeredReplayDiff, type LineageId, type LockHandle, type LockMetadata, MIN_SUPPORTED_VERSION, MigrationManager, type MigrationResult, type MigrationStatus, type NetworkId, NetworkIdSchema, type ReplayContext, type RotationResult, type RpcEndpointId, type RuntimeContext, type RuntimeNoiseDiff, SOMPI_PER_KAS, type SchemaMetadata, type SchemaVersion, type SemanticDriftReport, type SemanticIdentity, type Severity, type SnapshotManifest, type StampedEvent, type StateProvenance, type StructuralDiff, TelemetryManager, TelemetryRotator, type TelemetrySubsystem, type TxId, type UnknownEventPayload, type WorkflowId, type WriteFileAtomicOptions, acquireLock, artifactTypeSchema, asArtifactId, asContentHash, asCorrelationId, asDaaScore, asEventId, asEventSequence, asKaspaAddress, asLineageId, asNetworkId, asRpcEndpointId, asTxId, asWorkflowId, assertKnownArtifactType, assertNoSemanticDrift, attachLedgerAppender, classifyArtifactStatus, clearLock, comparePrePostMigrationLineage, coreEvents, createEventEnvelope, createKaspaP2shBlake2bLock, createPushOnlySignatureScript, createRedeemScriptHash, createSnapshot, describeArtifactType, detectSemanticDrift, deterministicCompare, diffReplays, executionModeSchema, formatCorruptionIssue, formatSignedSompiToKas, formatSompiToKas, getTelemetry, globalTelemetry, hardkasConfigSchema, isKnownArtifactType, isProcessAlive, kaspaNetworkIdSchema, listLocks, maskSecrets, migrateArtifact, parseHardkasConfig, parseKasToSompi, readSnapshotManifest, redactSecret, resolveCanonicalArtifact, resolveLineage, systemRuntimeContext, telemetryContextStorage, validateEventEnvelope, validateStatusTransition, verifyArtifactIntegrity, verifyCapabilityBoundary, verifyMigrationIntegrity, verifyProjectionFreshness, verifyReplay, withLock, withLocks, writeFileAtomic, writeFileAtomicSync };

package/dist/index.js

@@ -1,6 +1,249 @@
 // src/index.ts
 import { z } from "zod";
 
+// src/money.ts
+function parseKasToSompi(input) {
+  if (typeof input === "bigint") {
+    if (input < 0n) {
+      throw new Error("KAS_AMOUNT_NEGATIVE: negative money not allowed");
+    }
+    return input;
+  }
+  if (typeof input === "number") {
+    if (!Number.isSafeInteger(input)) {
+      throw new Error(
+        "KAS_AMOUNT_UNSAFE_NUMBER: floats or unsafe numbers are forbidden for monetary paths. Pass a string for KAS or bigint for Sompi."
+      );
+    }
+    if (input < 0) {
+      throw new Error("KAS_AMOUNT_NEGATIVE: negative money not allowed");
+    }
+    return BigInt(input);
+  }
+  if (typeof input !== "string") {
+    throw new Error("INVALID_KAS_AMOUNT: amount must be a string or bigint");
+  }
+  let cleaned = input.trim();
+  if (cleaned.startsWith("-")) {
+    throw new Error("KAS_AMOUNT_NEGATIVE: negative money not allowed");
+  }
+  if (cleaned.startsWith("+")) {
+    throw new Error("INVALID_KAS_AMOUNT: explicit positive sign not supported");
+  }
+  if (cleaned.toLowerCase().includes("e")) {
+    throw new Error(
+      "KAS_AMOUNT_SCIENTIFIC_NOTATION_UNSUPPORTED: scientific notation is not supported"
+    );
+  }
+  if (cleaned.toUpperCase().endsWith("KAS")) {
+    cleaned = cleaned.slice(0, -3).trim();
+  }
+  if (!/^[0-9]+(\.[0-9]+)?$/.test(cleaned)) {
+    throw new Error(`INVALID_KAS_AMOUNT: invalid characters or format in '${input}'`);
+  }
+  const parts = cleaned.split(".");
+  const integerPart = parts[0];
+  let fractionalPart = parts[1] || "";
+  if (fractionalPart.length > 8) {
+    throw new Error(
+      `KAS_AMOUNT_TOO_MANY_DECIMALS: too many decimal places in '${input}'`
+    );
+  }
+  fractionalPart = fractionalPart.padEnd(8, "0");
+  return BigInt(integerPart + fractionalPart);
+}
+function formatSompiToKas(sompi) {
+  let s;
+  try {
+    s = BigInt(sompi);
+  } catch (e) {
+    throw new Error("INVALID_KAS_AMOUNT: invalid sompi format");
+  }
+  if (s < 0n) {
+    throw new Error("SOMPI_AMOUNT_NEGATIVE: negative sompi amounts are not supported");
+  }
+  const str = s.toString().padStart(9, "0");
+  const intPart = str.slice(0, -8);
+  let fracPart = str.slice(-8);
+  fracPart = fracPart.replace(/0+$/, "");
+  if (fracPart.length > 0) {
+    return `${intPart}.${fracPart}`;
+  }
+  return intPart;
+}
+function formatSignedSompiToKas(sompi) {
+  let s;
+  try {
+    s = BigInt(sompi);
+  } catch (e) {
+    throw new Error("INVALID_KAS_AMOUNT: invalid sompi format");
+  }
+  if (s < 0n) {
+    return `-${formatSompiToKas(-s)}`;
+  }
+  return formatSompiToKas(s);
+}
+
+// src/registry.ts
+var HardkasSchemas = {
+  // --- Tx & Core ---
+  Event: "hardkas.event",
+  WorkflowIntent: "hardkas.workflow.intent",
+  TxPlan: "hardkas.txPlan",
+  TxPlanV1: "hardkas.txPlan.v1",
+  TxPlanV2: "hardkas.txPlan.v2",
+  SignedTx: "hardkas.signedTx",
+  SignedTxV1: "hardkas.signedTx.v1",
+  TxReceipt: "hardkas.txReceipt",
+  TxReceiptV1: "hardkas.txReceipt.v1",
+  TxTrace: "hardkas.txTrace",
+  TxTraceV1: "hardkas.txTrace.v1",
+  Snapshot: "hardkas.snapshot",
+  SnapshotV1: "hardkas.snapshot.v1",
+  WorkflowV1: "hardkas.workflow.v1",
+  PolicyV1: "hardkas.policy.v1",
+  AssumptionV1: "hardkas.assumption.v1",
+  NetworkProfileV1: "hardkas.networkProfile.v1",
+  MigrationReceiptV1: "hardkas.migrationReceipt.v1",
+  ErrorV1: "hardkas.error.v1",
+  ReplayV1: "hardkas.replay.v1",
+  ReplayDiffV1: "hardkas.replayDiff.v1",
+  ReplayReportV1: "hardkas.replayReport.v1",
+  ReplayVerifyV1: "hardkas.replayVerify.v1",
+  // --- Localnet & Realnet Infra ---
+  LocalnetStateV1: "hardkas.localnetState.v1",
+  LocalnetStatusV1: "hardkas.localnetStatus.v1",
+  LocalnetControlV1: "hardkas.localnetControl.v1",
+  LocalnetFundingV1: "hardkas.localnetFunding.v1",
+  RealAccountStoreV1: "hardkas.realAccountStore.v1",
+  EncryptedKeystoreV2: "hardkas.encryptedKeystore.v2",
+  NodeStatusV1: "hardkas.nodeStatus.v1",
+  // --- Deployment ---
+  DeploymentV1: "hardkas.deployment.v1",
+  DeploymentIndexV1: "hardkas.deploymentIndex.v1",
+  // --- L2 & Igra ---
+  IgraTxPlan: "hardkas.igraTxPlan",
+  IgraTxPlanV1: "hardkas.igraTxPlan.v1",
+  IgraSignedTxV1: "hardkas.igraSignedTx.v1",
+  IgraTxReceipt: "hardkas.igraTxReceipt",
+  IgraTxReceiptV1: "hardkas.igraTxReceipt.v1",
+  L2ProfileV1: "hardkas.l2Profile.v1",
+  L2BridgeAssumptionsV1: "hardkas.l2BridgeAssumptions.v1",
+  // --- SilverScript ---
+  SilverCompile: "hardkas.silver.compile",
+  SilverTest: "hardkas.silver.test",
+  SilverDeployPlan: "hardkas.silver.deployPlan",
+  SilverDeploy: "hardkas.silver.deploy",
+  SilverSpendPlan: "hardkas.silver.spendPlan",
+  SilverSpendReceipt: "hardkas.silver.spendReceipt",
+  SilverDeploySimulation: "hardkas.silver.deploySimulation",
+  SilverSpendSimulation: "hardkas.silver.spendSimulation",
+  SilverSimulationStateV1: "hardkas.silver.simulationState.v1",
+  // --- Programmability Surface ---
+  ProgrammabilityCapabilitiesV1: "hardkas.programmability.capabilities.v1",
+  ProgrammabilityInspectV1: "hardkas.programmability.inspect.v1",
+  ProgrammabilityVerifyV1: "hardkas.programmability.verify.v1",
+  ProgrammabilityCorpusReportV1: "hardkas.programmability.corpusReport.v1",
+  ProgrammabilityAppPlanV1: "hardkas.programmability.appPlan.v1",
+  ProgrammabilitySurfaceCheckV1: "hardkas.programmability.surfaceCheck.v1",
+  ProgrammabilityExamplesCheckV1: "hardkas.programmability.examplesCheck.v1",
+  ProgrammabilityTemplatesCheckV1: "hardkas.programmability.templatesCheck.v1",
+  // --- ZK & vProgs ---
+  ZkCapabilitiesV1: "hardkas.zkCapabilities.v1",
+  ZkCorpusV1: "hardkas.zkCorpus.v1",
+  ZkProofInspectV1: "hardkas.zkProofInspect.v1",
+  ZkProofVerificationV1: "hardkas.zkProofVerification.v1",
+  ZkCorpusVerificationV1: "hardkas.zkCorpusVerification.v1",
+  ZkGroth16FixtureV1: "hardkas.zkGroth16Fixture.v1",
+  ZkRisc0FixtureV1: "hardkas.zkRisc0Fixture.v1",
+  ZkGroth16ProofV1: "hardkas.zk.groth16.proof.v1",
+  ZkGroth16PublicInputsV1: "hardkas.zk.groth16.publicInputs.v1",
+  ZkGroth16VerificationKeyV1: "hardkas.zk.groth16.verificationKey.v1",
+  ZkGroth16VerifierMetadataV1: "hardkas.zk.groth16.verifierMetadata.v1",
+  ZkGroth16VerifyReportV1: "hardkas.zk.groth16.verifyReport.v1",
+  ZkRisc0ImageIdV1: "hardkas.zk.risc0.imageId.v1",
+  ZkRisc0JournalV1: "hardkas.zk.risc0.journal.v1",
+  ZkRisc0ReceiptV1: "hardkas.zk.risc0.receipt.v1",
+  ZkRisc0VerifyReportV1: "hardkas.zk.risc0.verifyReport.v1",
+  VProgsCapabilitiesV1: "hardkas.vprogsCapabilities.v1",
+  VProgsInspectV1: "hardkas.vprogsInspect.v1",
+  VProgsStatusV1: "hardkas.vprogsStatus.v1",
+  VProgsInspectFixtureV1: "hardkas.vprogs.inspectFixture.v1",
+  // --- Corpus & Testing ---
+  ToccataProgrammabilityCorpusV1: "hardkas.toccataProgrammabilityCorpus.v1",
+  ToccataGauntletV1: "hardkas.toccataGauntlet.v1",
+  ToccataCorpusV1: "hardkas.toccataCorpus.v1",
+  ToccataGoldenCompareV1: "hardkas.toccataGoldenCompare.v1",
+  ToccataGoldenFailureCaseV1: "hardkas.toccataGoldenFailureCase.v1",
+  ToccataGoldenManifestV1: "hardkas.toccataGoldenManifest.v1",
+  ToccataGoldenFailureManifestV1: "hardkas.toccataGoldenFailureManifest.v1",
+  // --- CLI / Runners / Audits / Reports ---
+  PostReleaseProbe: "hardkas.postReleaseProbe",
+  CliReferenceV1: "hardkas.cliReference.v1",
+  ArtifactV1: "hardkas.artifact.v1",
+  ArtifactInspectV1: "hardkas.artifactInspect.v1",
+  AuditV1: "hardkas.audit.v1",
+  PostReleaseBreakGauntletV1: "hardkas.postReleaseBreakGauntlet.v1",
+  KaspaDoctorV1: "hardkas.kaspaDoctor.v1",
+  DevDoctorV1: "hardkas.devDoctor.v1",
+  DevServerV1: "hardkas.devServer.v1",
+  LocalWizardV1: "hardkas.localWizard.v1",
+  QueryRebuildV1: "hardkas.queryRebuild.v1",
+  QueryVerifyV1: "hardkas.queryVerify.v1",
+  SemanticBundleV1: "hardkas.semantic-bundle.v1",
+  SessionV1: "hardkas.session.v1",
+  SessionV0: "hardkas.session.v0",
+  TelemetryV1: "hardkas.telemetry.v1",
+  TortureReportV1: "hardkas.tortureReport.v1",
+  PruneReportV1: "hardkas.pruneReport.v1",
+  LockV1: "hardkas.lock.v1",
+  BridgeLocalPlanV1: "hardkas.bridge.localPlan.v1",
+  BridgeLocalSimulationV1: "hardkas.bridge.localSimulation.v1",
+  KaswareLocalV1: "hardkas.kaswareLocal.v1",
+  MetamaskLocalV1: "hardkas.metamaskLocal.v1",
+  // Miscellaneous used in docs / examples
+  ExampleDocumentAnchorV1: "hardkas.example.documentAnchor.v1"
+};
+var ArtifactTypes = HardkasSchemas;
+var registryValues = new Set(Object.values(HardkasSchemas));
+function isKnownArtifactType(type) {
+  return registryValues.has(type);
+}
+function assertKnownArtifactType(type) {
+  if (!isKnownArtifactType(type)) {
+    throw new Error(`Unknown HardKAS artifact type or schema: ${type}`);
+  }
+  return type;
+}
+function describeArtifactType(type) {
+  assertKnownArtifactType(type);
+  const isLegacy = !type.includes(".v") && !type.endsWith("V1");
+  return {
+    type,
+    domain: inferDomain(type),
+    version: isLegacy ? "legacy" : type.split(".").pop() || "unknown",
+    stability: inferStability(type),
+    legacy: isLegacy
+  };
+}
+function inferDomain(type) {
+  if (type.includes("silver")) return "silver";
+  if (type.includes("zk") || type.includes("groth16") || type.includes("risc0")) return "zk";
+  if (type.includes("vprog")) return "vprogs";
+  if (type.includes("programmability")) return "programmability";
+  if (type.includes("corpus") || type.includes("toccata") || type.includes("toccataGolden") || type.includes("Fixture")) return "corpus";
+  if (type.includes("cli") || type.includes("Runner") || type.includes("report") || type.includes("audit") || type.includes("Doctor")) return "audit";
+  if (type.includes("tx") || type.includes("snapshot") || type.includes("receipt") || type.includes("policy")) return "tx";
+  return "infra";
+}
+function inferStability(type) {
+  if (type.includes("toccataGolden") || type.includes("Fixture")) return "fixture-coherence";
+  if (type.includes("Inspect") || type.includes("inspect")) return "inspect-only";
+  if (type.includes("Report") || type.includes("report") || type.includes("Audit") || type.includes("audit")) return "report";
+  if (type.includes("v1")) return "stable";
+  return "stable-local";
+}
+
 // src/append-coordinator.ts
 import fs from "fs";
 import path2 from "path";
@@ -54,7 +297,7 @@ var TelemetryManager = class {
     const eventIdRaw = `${eventHash}-${nowStr}`;
     const eventId = crypto2.createHash("sha256").update(eventIdRaw).digest("hex").slice(0, 32);
     const event = {
-      schemaVersion: "hardkas.telemetry.v1",
+      schemaVersion: HardkasSchemas.TelemetryV1,
       eventId,
       eventHash,
       timestamp: nowStr,
@@ -355,7 +598,7 @@ var coreEvents = new CoreEventBus();
 function createEventEnvelope(params) {
   const timestamp = (/* @__PURE__ */ new Date()).toISOString();
   return {
-    schema: "hardkas.event",
+    schema: HardkasSchemas.Event,
     version: "1.0.0",
     eventId: params.eventId || crypto.randomUUID(),
     domain: params.domain,
@@ -376,7 +619,7 @@ function createEventEnvelope(params) {
 }
 function validateEventEnvelope(event) {
   if (!event || typeof event !== "object") return false;
-  if (event.schema !== "hardkas.event") return false;
+  if (event.schema !== HardkasSchemas.Event) return false;
   if (!event.eventId || !event.domain || !event.kind) return false;
   if (!event.workflowId || !event.correlationId || !event.networkId) return false;
   if (typeof event.payload !== "object") return false;
@@ -634,7 +877,7 @@ async function acquireLock(args) {
   while (true) {
     try {
       const metadata = {
-        schema: "hardkas.lock.v1",
+        schema: HardkasSchemas.LockV1,
         name: args.name,
         pid: process.pid,
         command: args.command || process.argv.join(" "),
@@ -853,7 +1096,7 @@ function clearLock(rootDir, name, options = {}) {
 // src/replay.ts
 function diffReplays(replayA, replayB) {
   const diff = {
-    schema: "hardkas.replayDiff.v1",
+    schema: HardkasSchemas.ReplayDiffV1,
     structural: {
       missingArtifacts: [],
       excludedArtifacts: [],
@@ -956,7 +1199,7 @@ async function createSnapshot(options) {
   const manifest = {
     snapshotVersion: 1,
     createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-    hardkasVersion: "0.8.20-alpha",
+    hardkasVersion: "0.9.1-alpha",
     stateAuthority: "filesystem",
     projectionAuthority: "sqlite",
     deterministicScope,
@@ -1205,7 +1448,7 @@ Resolution Command: ${report.exactReplayCommand}`
 // src/migrations.ts
 import fs6 from "fs";
 import path8 from "path";
-var CURRENT_RUNTIME_VERSION = "0.8.20-alpha";
+var CURRENT_RUNTIME_VERSION = "0.9.1-alpha";
 var MIN_SUPPORTED_VERSION = "0.5.0-alpha";
 var MigrationManager = class {
   static checkVersion(rootDir) {
@@ -1252,7 +1495,10 @@ var MigrationManager = class {
     }
     if (!status.needsMigration) return;
     if (dryRun) {
-      console.log(
+      getTelemetry().logAnomaly(
+        "EXTERNAL_MUTATION",
+        "low",
+        "projection",
         `[DRY-RUN] Would migrate workspace from ${status.currentVersion} to ${CURRENT_RUNTIME_VERSION}`
       );
       return;
@@ -1299,6 +1545,92 @@ var MigrationManager = class {
   }
 };
 
+// src/silver.ts
+import { blake2b } from "@noble/hashes/blake2.js";
+function normalizeScriptBytes(scriptHexOrBytes) {
+  if (Buffer.isBuffer(scriptHexOrBytes)) return scriptHexOrBytes;
+  if (scriptHexOrBytes instanceof Uint8Array) return Buffer.from(scriptHexOrBytes);
+  if (typeof scriptHexOrBytes !== "string") {
+    throw new HardkasError("SILVERSCRIPT_INVALID_REDEEM_SCRIPT", "Must be hex string or buffer");
+  }
+  const hex = scriptHexOrBytes.trim();
+  if (hex === "") {
+    throw new HardkasError("SILVERSCRIPT_INVALID_REDEEM_SCRIPT", "Redeem script cannot be empty");
+  }
+  if (!/^[0-9a-fA-F]*$/.test(hex) || hex.length % 2 !== 0) {
+    throw new HardkasError("SILVERSCRIPT_INVALID_REDEEM_SCRIPT", "Redeem script must be valid even-length hex");
+  }
+  return Buffer.from(hex, "hex");
+}
+function createRedeemScriptHash(scriptHexOrBytes) {
+  const scriptBytes = normalizeScriptBytes(scriptHexOrBytes);
+  const redeemScriptHashBytes = blake2b(scriptBytes, { dkLen: 32 });
+  return Buffer.from(redeemScriptHashBytes).toString("hex");
+}
+function createKaspaP2shBlake2bLock(scriptHexOrBytes) {
+  const redeemScriptHash = createRedeemScriptHash(scriptHexOrBytes);
+  const lockingScriptHex = `aa20${redeemScriptHash}87`;
+  const redeemScriptHex = normalizeScriptBytes(scriptHexOrBytes).toString("hex");
+  return {
+    scriptPublicKeyVersion: 0,
+    lockingScriptHex,
+    redeemScriptHash,
+    redeemScriptHex
+  };
+}
+function getPushDataPrefix(byteCount) {
+  if (byteCount < 0) {
+    throw new HardkasError("SILVERSCRIPT_INVALID_PUSHDATA", "Negative byte count");
+  }
+  if (byteCount === 0) {
+    return "00";
+  }
+  if (byteCount <= 75) {
+    return byteCount.toString(16).padStart(2, "0");
+  }
+  if (byteCount <= 255) {
+    return `4c${byteCount.toString(16).padStart(2, "0")}`;
+  }
+  if (byteCount <= 65535) {
+    const hex2 = byteCount.toString(16).padStart(4, "0");
+    const le2 = hex2.substring(2, 4) + hex2.substring(0, 2);
+    return `4d${le2}`;
+  }
+  const hex = byteCount.toString(16).padStart(8, "0");
+  const le = hex.substring(6, 8) + hex.substring(4, 6) + hex.substring(2, 4) + hex.substring(0, 2);
+  return `4e${le}`;
+}
+function createPushOnlySignatureScript(args, redeemScriptHex) {
+  if (!redeemScriptHex || redeemScriptHex.trim() === "") {
+    throw new HardkasError(
+      "SILVERSCRIPT_INVALID_REDEEM_SCRIPT",
+      "Redeem script cannot be empty"
+    );
+  }
+  if (!/^[0-9a-fA-F]*$/.test(redeemScriptHex) || redeemScriptHex.length % 2 !== 0) {
+    throw new HardkasError(
+      "SILVERSCRIPT_INVALID_REDEEM_SCRIPT",
+      "Redeem script must be valid hex"
+    );
+  }
+  let signatureScript = "";
+  for (const argHex of args) {
+    if (!/^[0-9a-fA-F]*$/.test(argHex) || argHex.length % 2 !== 0) {
+      throw new HardkasError(
+        "SILVERSCRIPT_SIGNATURE_SCRIPT_NOT_PUSH_ONLY",
+        `Argument must be valid hex: ${argHex}`
+      );
+    }
+    const byteCount = argHex.length / 2;
+    const prefix = getPushDataPrefix(byteCount);
+    signatureScript += prefix + argHex;
+  }
+  const redeemScriptByteCount = redeemScriptHex.length / 2;
+  const redeemPrefix = getPushDataPrefix(redeemScriptByteCount);
+  signatureScript += redeemPrefix + redeemScriptHex;
+  return signatureScript;
+}
+
 // src/index.ts
 var SOMPI_PER_KAS = 100000000n;
 var kaspaNetworkIdSchema = z.enum([
@@ -1323,7 +1655,15 @@ var artifactTypeSchema = z.enum([
   "policy.v1",
   "networkProfile.v1",
   "assumption.v1",
-  "migrationReceipt.v1"
+  "migrationReceipt.v1",
+  "silver.compile",
+  "silver.test",
+  "silver.spendPlan",
+  "silver.deployPlan",
+  "silver.deploy",
+  "silver.spendReceipt",
+  "silver.deploySimulation",
+  "silver.spendSimulation"
 ]);
 var NetworkIdSchema = kaspaNetworkIdSchema;
 var ExecutionModeSchema = executionModeSchema;
@@ -1375,31 +1715,15 @@ function parseHardkasConfig(input) {
   }
   return result.data;
 }
-function parseKasToSompi(input) {
-  const trimmed = input.trim();
-  if (!/^\d+(\.\d{1,8})?$/.test(trimmed)) {
-    throw new HardkasError("AMOUNT_INVALID", `Invalid KAS amount: ${input}`);
-  }
-  const [whole, fractional = ""] = trimmed.split(".");
-  if (whole === void 0) {
-    throw new HardkasError("AMOUNT_INVALID", `Invalid KAS amount: ${input}`);
-  }
-  return BigInt(whole) * SOMPI_PER_KAS + BigInt(fractional.padEnd(8, "0"));
-}
-function formatSompi(amountSompi) {
-  const sign = amountSompi < 0n ? "-" : "";
-  const absolute = amountSompi < 0n ? -amountSompi : amountSompi;
-  const whole = absolute / SOMPI_PER_KAS;
-  const fractional = absolute % SOMPI_PER_KAS;
-  return `${sign}${whole}.${fractional.toString().padStart(8, "0")} KAS`;
-}
 export {
   AppendCoordinator,
   ArtifactTypeSchema,
+  ArtifactTypes,
   CURRENT_RUNTIME_VERSION,
   EnvironmentTelemetry,
   ExecutionModeSchema,
   HardkasError,
+  HardkasSchemas,
   InvariantViolationError,
   LOCK_ORDER,
   MIN_SUPPORTED_VERSION,
@@ -1422,6 +1746,7 @@ export {
   asRpcEndpointId,
   asTxId,
   asWorkflowId,
+  assertKnownArtifactType,
   assertNoSemanticDrift,
   attachLedgerAppender,
   classifyArtifactStatus,
@@ -1429,16 +1754,22 @@ export {
   comparePrePostMigrationLineage,
   coreEvents,
   createEventEnvelope,
+  createKaspaP2shBlake2bLock,
+  createPushOnlySignatureScript,
+  createRedeemScriptHash,
   createSnapshot,
+  describeArtifactType,
   detectSemanticDrift,
   deterministicCompare,
   diffReplays,
   executionModeSchema,
   formatCorruptionIssue,
-  formatSompi,
+  formatSignedSompiToKas,
+  formatSompiToKas,
   getTelemetry,
   globalTelemetry,
   hardkasConfigSchema,
+  isKnownArtifactType,
   isProcessAlive,
   kaspaNetworkIdSchema,
   listLocks,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardkas/core",
-  "version": "0.8.20-alpha",
+  "version": "0.9.1-alpha",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -12,6 +12,7 @@
     }
   },
   "dependencies": {
+    "@noble/hashes": "^2.2.0",
     "pino": "^9.5.0",
     "zod": "^3.24.1"
   },