{"_id":"@altopelago/sansa","_rev":"6-68941e0820fc2ff50fff524a78a7a2b1","name":"@altopelago/sansa","dist-tags":{"latest":"0.11.1"},"versions":{"0.9.0":{"name":"@altopelago/sansa","version":"0.9.0","keywords":["sansa","aeonite","aeon","address","addressing","resolve","query","parser"],"license":"MIT","_id":"@altopelago/sansa@0.9.0","maintainers":[{"name":"altopelago","email":"aeon@altopelago.com"}],"homepage":"https://github.com/AltoPelago/sansa#readme","bugs":{"url":"https://github.com/AltoPelago/sansa/issues"},"bin":{"sansa-query":"scripts/query.mjs"},"dist":{"shasum":"ddbbbd7e42de25fed06f44e652bd0a84631594c8","tarball":"https://registry.npmjs.org/@altopelago/sansa/-/sansa-0.9.0.tgz","fileCount":33,"integrity":"sha512-vDNcXXFRFrd/vFn+jr4wqIHF64ihknqvc9w8btGhfjLsmhIKMfc5FW9cssfY9AJHqm/1E2tur8r98CXijFFwVA==","signatures":[{"sig":"MEYCIQCla0wZ63107vRG73JFOBAiS5NiK8OtmG+WUioFpZ32/wIhALvxm+/jplZCT0HIwWgmAHnKx0KKcAMMlZyoS7VBTNxw","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":344118},"main":"./src/index.js","type":"module","types":"./src/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./src/index.d.ts","import":"./src/index.js"}},"gitHead":"c831762553d2656cbcb084528c95805ee4261f34","scripts":{"cts":"npm run cts:value-semantics && npm run cts:address && npm run cts:resolve && npm run cts:query","test":"node --test test/*.test.js","query":"node scripts/query.mjs","stress":"node scripts/stress-addresses.mjs","cts:query":"node scripts/cts-query.mjs","query:web":"node scripts/query-web.mjs","cts:address":"node scripts/cts-address.mjs","cts:resolve":"node scripts/cts-resolve.mjs","cts:value-semantics":"node scripts/cts-value-semantics.mjs","cts:query:experimental":"node scripts/cts-query.mjs --include-experimental"},"_npmUser":{"name":"altopelago","email":"aeon@altopelago.com"},"repository":{"url":"git+https://github.com/AltoPelago/sansa.git","type":"git"},"_npmVersion":"11.13.0","description":"Semantic Address NameSpace Abstraction parser, resolver, and query toolkit.","directories":{},"sideEffects":false,"_nodeVersion":"24.16.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sansa_0.9.0_1784831526769_0.24734422525497757","host":"s3://npm-registry-packages-npm-production"}},"0.9.1":{"name":"@altopelago/sansa","version":"0.9.1","keywords":["sansa","aeonite","aeon","address","addressing","resolve","query","parser"],"license":"MIT","_id":"@altopelago/sansa@0.9.1","maintainers":[{"name":"altopelago","email":"aeon@altopelago.com"}],"homepage":"https://github.com/AltoPelago/sansa#readme","bugs":{"url":"https://github.com/AltoPelago/sansa/issues"},"bin":{"sansa-query":"scripts/query.mjs","sansa-instruction":"scripts/instruction.mjs"},"dist":{"shasum":"9f72eed10a9f812823107b2bb77bbcff94b305f4","tarball":"https://registry.npmjs.org/@altopelago/sansa/-/sansa-0.9.1.tgz","fileCount":46,"integrity":"sha512-or1t3FhXq0Fy5UEXqvT81ksTnO3OXusexfgz+MgYix8vdP2yeIrJEvyyjrUtporoyOab23VpDSFpY3qshLdI4w==","signatures":[{"sig":"MEQCIDySIcuYGM9GSDQX8gaGzuro64vEQ+DLmvopCgatFzZgAiBU47SLapVwWRjtDFjoC72LBvKxmucWNpFLSJPfSvvCvQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@altopelago%2fsansa@0.9.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":812691},"main":"./src/index.js","type":"module","types":"./src/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./src/index.d.ts","import":"./src/index.js"}},"gitHead":"41fd4f9afd941a3a6cb19cbcd64c9c26b6beb6dc","scripts":{"cts":"npm run cts:value-semantics && npm run cts:address && npm run cts:resolve && npm run cts:query","test":"node --test test/*.test.js","query":"node scripts/query.mjs","stress":"node scripts/stress-addresses.mjs","cts:query":"node scripts/cts-query.mjs","query:web":"node scripts/query-web.mjs","cts:mutate":"node scripts/cts-mutate.mjs","mutate:web":"node scripts/query-web.mjs","cts:address":"node scripts/cts-address.mjs","cts:resolve":"node scripts/cts-resolve.mjs","instruction":"node scripts/instruction.mjs","cts:instruction":"node scripts/cts-instruction.mjs","cts:value-semantics":"node scripts/cts-value-semantics.mjs","validate:cts-claims":"node scripts/validate-cts-claims.mjs","cts:query:experimental":"node scripts/cts-query.mjs --include-experimental"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:25d346b2-5098-4882-bac4-8f76eceea7e1"}},"repository":{"url":"git+https://github.com/AltoPelago/sansa.git","type":"git"},"_npmVersion":"11.16.0","description":"Semantic Address NameSpace Abstraction parser, resolver, and query toolkit.","directories":{},"sideEffects":false,"_nodeVersion":"24.18.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sansa_0.9.1_1785676004000_0.8270623510176567","host":"s3://npm-registry-packages-npm-production"}},"0.10.0":{"name":"@altopelago/sansa","version":"0.10.0","keywords":["sansa","aeonite","aeon","address","addressing","resolve","query","parser"],"license":"MIT","_id":"@altopelago/sansa@0.10.0","maintainers":[{"name":"altopelago","email":"aeon@altopelago.com"}],"homepage":"https://github.com/AltoPelago/sansa#readme","bugs":{"url":"https://github.com/AltoPelago/sansa/issues"},"bin":{"sansa-query":"scripts/query.mjs","sansa-instruction":"scripts/instruction.mjs"},"dist":{"shasum":"1e69cb25d349189151f932ec736bce1373c64548","tarball":"https://registry.npmjs.org/@altopelago/sansa/-/sansa-0.10.0.tgz","fileCount":46,"integrity":"sha512-WpS6DBBwAqgOfFQn1YG3cYmYy6NdOsQy5Foc6QqBemZfsPoIU0ePirLYOM5w+mpKfw9rh+vA04rvA4rxovWpAQ==","signatures":[{"sig":"MEQCIC9N4FDS1jAQXax7WU23MwCSfrH7ixuIOsp7dZjbPLOyAiBMFURWXC9s/OYVifuc3HIFemKVqleesx8cE6k3bR2lpw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@altopelago%2fsansa@0.10.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":835607},"main":"./src/index.js","type":"module","types":"./src/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./src/index.d.ts","import":"./src/index.js"}},"gitHead":"92b09394d1c36ae26b68a19ee9e1ed3b46e10a8c","scripts":{"cts":"npm run cts:value-semantics && npm run cts:address && npm run cts:resolve && npm run cts:query","test":"node --test test/*.test.js","query":"node scripts/query.mjs","stress":"node scripts/stress-addresses.mjs","cts:query":"node scripts/cts-query.mjs","query:web":"node scripts/query-web.mjs","cts:mutate":"node scripts/cts-mutate.mjs","mutate:web":"node scripts/query-web.mjs","cts:address":"node scripts/cts-address.mjs","cts:resolve":"node scripts/cts-resolve.mjs","instruction":"node scripts/instruction.mjs","cts:instruction":"node scripts/cts-instruction.mjs","cts:value-semantics":"node scripts/cts-value-semantics.mjs","validate:cts-claims":"node scripts/validate-cts-claims.mjs","cts:query:experimental":"node scripts/cts-query.mjs --include-experimental"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:25d346b2-5098-4882-bac4-8f76eceea7e1"}},"repository":{"url":"git+https://github.com/AltoPelago/sansa.git","type":"git"},"_npmVersion":"11.17.0","description":"Semantic Address NameSpace Abstraction parser, resolver, and query toolkit.","directories":{},"sideEffects":false,"_nodeVersion":"24.19.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sansa_0.10.0_1788189988573_0.32199509415577254","host":"s3://npm-registry-packages-npm-production"}},"0.10.1":{"name":"@altopelago/sansa","version":"0.10.1","keywords":["sansa","aeonite","aeon","address","addressing","resolve","query","parser"],"license":"MIT","_id":"@altopelago/sansa@0.10.1","maintainers":[{"name":"altopelago","email":"aeon@altopelago.com"}],"homepage":"https://github.com/AltoPelago/sansa#readme","bugs":{"url":"https://github.com/AltoPelago/sansa/issues"},"bin":{"sansa-query":"scripts/query.mjs","sansa-instruction":"scripts/instruction.mjs"},"dist":{"shasum":"9b956a7098c9c395e4d3e03d2d66264679df36ab","tarball":"https://registry.npmjs.org/@altopelago/sansa/-/sansa-0.10.1.tgz","fileCount":47,"integrity":"sha512-+azHv/BZiP+84OGO15FwbfUwIU1BhlKQC2DOoDHFajf2FVe8iB9GrviLJ+gW7C7cI/wj+xhBu14YyTT2Lr7Nog==","signatures":[{"sig":"MEYCIQDWnzMN7cpOQk7qKJ/LAD9eRcFipzJAdUzfEfA1BHL4sAIhAIrA3LQEjw6jMzEFdnqb6UNtP5uw3oqMgXK/MEvwicyB","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@altopelago%2fsansa@0.10.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":885987},"main":"./src/index.js","type":"module","types":"./src/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./src/index.d.ts","import":"./src/index.js"}},"gitHead":"efd65e86c59f21a952d03240b5b065656dd677cf","scripts":{"cts":"npm run cts:value-semantics && npm run cts:address && npm run cts:resolve && npm run cts:query","test":"node --test test/*.test.js","query":"node scripts/query.mjs","stress":"node scripts/stress-addresses.mjs","cts:query":"node scripts/cts-query.mjs","query:web":"node scripts/query-web.mjs","cts:mutate":"node scripts/cts-mutate.mjs","mutate:web":"node scripts/query-web.mjs","cts:address":"node scripts/cts-address.mjs","cts:resolve":"node scripts/cts-resolve.mjs","instruction":"node scripts/instruction.mjs","cts:instruction":"node scripts/cts-instruction.mjs","cts:value-semantics":"node scripts/cts-value-semantics.mjs","validate:cts-claims":"node scripts/validate-cts-claims.mjs","cts:query:experimental":"node scripts/cts-query.mjs --include-experimental"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:25d346b2-5098-4882-bac4-8f76eceea7e1"}},"repository":{"url":"git+https://github.com/AltoPelago/sansa.git","type":"git"},"_npmVersion":"11.19.0","description":"Semantic Address NameSpace Abstraction parser, resolver, and query toolkit.","directories":{},"sideEffects":false,"_nodeVersion":"24.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sansa_0.10.1_1789055982210_0.569544812348822","host":"s3://npm-registry-packages-npm-production"}},"0.11.0":{"name":"@altopelago/sansa","version":"0.11.0","keywords":["sansa","aeonite","aeon","address","addressing","resolve","query","parser"],"license":"MIT","_id":"@altopelago/sansa@0.11.0","maintainers":[{"name":"altopelago","email":"aeon@altopelago.com"}],"homepage":"https://github.com/AltoPelago/sansa#readme","bugs":{"url":"https://github.com/AltoPelago/sansa/issues"},"bin":{"sansa-query":"scripts/query.mjs","sansa-instruction":"scripts/instruction.mjs"},"dist":{"shasum":"8f79f3fa2f87ff02fe0c481fb9193affaf12714a","tarball":"https://registry.npmjs.org/@altopelago/sansa/-/sansa-0.11.0.tgz","fileCount":48,"integrity":"sha512-FlCdwz2T13Xpdc5D7AyFvbSC3DrKyATeRxPHJ1qfjdeLFQ92GRVDi+p0bh2JZw2TvGnnfK8uD5Mzxc3FLiviig==","signatures":[{"sig":"MEUCIQCD48JHgE56Cq1ITTEn0O2ok9dcil3oR0NmuJ1kn2RshAIgfaBZBvl5xbOdD7GOKjAtizK/yqzEEYJQGSbrInLzxzU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@altopelago%2fsansa@0.11.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":907825},"main":"./src/index.js","type":"module","types":"./src/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./src/index.d.ts","import":"./src/index.js"}},"gitHead":"ac040e22b279210ad2381e37e0b32b3e7967e4c6","scripts":{"cts":"npm run cts:value-semantics && npm run cts:address && npm run cts:resolve && npm run cts:query","test":"node --test test/*.test.js","query":"node scripts/query.mjs","stress":"node scripts/stress-addresses.mjs","cts:query":"node scripts/cts-query.mjs","query:web":"node scripts/query-web.mjs","cts:mutate":"node scripts/cts-mutate.mjs","mutate:web":"node scripts/query-web.mjs","cts:address":"node scripts/cts-address.mjs","cts:resolve":"node scripts/cts-resolve.mjs","instruction":"node scripts/instruction.mjs","version:set":"node scripts/version.mjs set","version:check":"node scripts/version.mjs check","cts:instruction":"node scripts/cts-instruction.mjs","version:recover":"node scripts/version.mjs recover","cts:value-semantics":"node scripts/cts-value-semantics.mjs","validate:cts-claims":"node scripts/validate-cts-claims.mjs","cts:query:experimental":"node scripts/cts-query.mjs --include-experimental"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:25d346b2-5098-4882-bac4-8f76eceea7e1"}},"repository":{"url":"git+https://github.com/AltoPelago/sansa.git","type":"git"},"_npmVersion":"11.19.0","description":"Semantic Address NameSpace Abstraction parser, resolver, and query toolkit.","directories":{},"sideEffects":false,"_nodeVersion":"24.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sansa_0.11.0_1789379352758_0.8869573787557397","host":"s3://npm-registry-packages-npm-production"}},"0.11.1":{"name":"@altopelago/sansa","version":"0.11.1","description":"Semantic Address NameSpace Abstraction parser, resolver, and query toolkit.","license":"MIT","type":"module","main":"./src/index.js","types":"./src/index.d.ts","exports":{".":{"types":"./src/index.d.ts","import":"./src/index.js"}},"bin":{"sansa-query":"scripts/query.mjs","sansa-instruction":"scripts/instruction.mjs"},"sideEffects":false,"engines":{"node":">=20.0.0"},"repository":{"type":"git","url":"git+https://github.com/AltoPelago/sansa.git"},"bugs":{"url":"https://github.com/AltoPelago/sansa/issues"},"homepage":"https://github.com/AltoPelago/sansa#readme","publishConfig":{"access":"public"},"scripts":{"cts":"npm run cts:value-semantics && npm run cts:address && npm run cts:resolve && npm run cts:query","cts:value-semantics":"node scripts/cts-value-semantics.mjs","cts:address":"node scripts/cts-address.mjs","cts:resolve":"node scripts/cts-resolve.mjs","cts:query":"node scripts/cts-query.mjs","cts:query:experimental":"node scripts/cts-query.mjs --include-experimental","cts:instruction":"node scripts/cts-instruction.mjs","cts:mutate":"node scripts/cts-mutate.mjs","instruction":"node scripts/instruction.mjs","query":"node scripts/query.mjs","query:web":"node scripts/query-web.mjs","mutate:web":"node scripts/query-web.mjs","stress":"node scripts/stress-addresses.mjs","version:set":"node scripts/version.mjs set","version:check":"node scripts/version.mjs check","version:recover":"node scripts/version.mjs recover","validate:cts-claims":"node scripts/validate-cts-claims.mjs","test":"node --test test/*.test.js"},"keywords":["sansa","aeonite","aeon","address","addressing","resolve","query","parser"],"gitHead":"195ff84042aed1b1d70cbce7829cf7b9465db2a2","_id":"@altopelago/sansa@0.11.1","_nodeVersion":"24.20.0","_npmVersion":"11.19.0","dist":{"integrity":"sha512-yVR3Pj2hM5+vuLCM70pvvAjR1sBoKylcmRgwq36zMtz0D2Yi5KoISCkLlqwexrnhvovad4VJmTPosmmJKacb2A==","shasum":"10982a8d55d33bde382b403e7debdcb536e4004d","tarball":"https://registry.npmjs.org/@altopelago/sansa/-/sansa-0.11.1.tgz","fileCount":48,"unpackedSize":910557,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@altopelago%2fsansa@0.11.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC7CK+O0PwUS5W4ArDYLG6LwZF/giIxEgg23VnGfyGgvgIhAPfOokaVMDFJtszAnG+aOSLaVrrlXTkL2IM/+kVrAwqm"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:25d346b2-5098-4882-bac4-8f76eceea7e1"}},"directories":{},"maintainers":[{"name":"altopelago","email":"aeon@altopelago.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sansa_0.11.1_1789382677860_0.06702868521585215"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-23T18:32:06.603Z","modified":"2026-09-14T10:44:38.302Z","0.9.0":"2026-07-23T18:32:06.918Z","0.9.1":"2026-08-02T13:06:44.163Z","0.10.0":"2026-08-31T15:26:28.749Z","0.10.1":"2026-09-10T15:59:42.353Z","0.11.0":"2026-09-14T09:49:12.899Z","0.11.1":"2026-09-14T10:44:38.022Z"},"bugs":{"url":"https://github.com/AltoPelago/sansa/issues"},"license":"MIT","homepage":"https://github.com/AltoPelago/sansa#readme","keywords":["sansa","aeonite","aeon","address","addressing","resolve","query","parser"],"repository":{"type":"git","url":"git+https://github.com/AltoPelago/sansa.git"},"description":"Semantic Address NameSpace Abstraction parser, resolver, and query toolkit.","maintainers":[{"name":"altopelago","email":"aeon@altopelago.com"}],"readme":"# SANSA\n\nShared Semantic Address NameSpace Abstraction (SANSA) address, resolve, query, instruction, and mutation-planning model.\n\nThis package is the first implementation package for SANSA Address, SANSA Resolve, and SANSA.Query, with experimental SANSA.Instruction parsing/lowering and an experimental structured-plan API for SANSA.Mutate. It parses and renders SANSA address expressions, resolves those expressions against a host-supplied namespace adapter, parses the SANSA.Query clause and expression surfaces, and evaluates a bounded query subset over host-neutral bindings. It also exposes the Shared AEON Value Semantics minimum consumer contract used by Query for concrete value predicates, equality, ordering behavior, and string profile hooks. The experimental Instruction API parses human-authored change intents, lowers them into structured Mutate requests, and can bridge into mutation planning. The experimental Mutate API plans exact create, replace, remove, insert, and same-container move operations, preserves datatype/kind value intent, enforces operation/precondition/value budgets, validates target-surface representability through a separate post-plan API, and applies plans only through host-supplied mutation hooks. It does not inspect host values directly beyond host-exposed binding metadata, apply host-specific authorization, provide transactions, decide schema legality, or assign semantics to qualifiers.\n\nImplementation capability metadata is recorded in [docs/capabilities.json](docs/capabilities.json). The package currently advertises `AEON.ValueSemantics`, `SANSA.Addressing`, `SANSA.Resolve`, `SANSA.Query`, Query budget controls, the experimental `validation` Query policy, experimental `SANSA.Transform` library extensions for `objectFrom` and `fieldsFrom`, experimental `SANSA.Instruction` parse/lower/plan bridging, an experimental `SANSA.Mutate` plan API, and the workbench-only experimental `sansa.mutate.policy.planFilter` slice.\n\nCTS snapshot claims are recorded in [conformance/cts-claims.json](conformance/cts-claims.json).\n\n## Current Scope\n\n- root selectors: `$`, `?`\n- member selectors: `.name`, `.[\"quoted.name\"]`\n- positional selectors: `[0]`, `[2..5]`, `[2..]`, `[..5]`\n- parent selector: `.^`\n- attribute address-space selector: `.@`\n- local address-space selector: `.<\"namespace\">`\n- expansion selectors: `.*`, `.**`\n- filters: `#type`, `%kind`\n- name pattern selector: `.(\"pattern\")`\n- qualified address literals with top-level qualifier unions\n- structural resolve over host bindings with exact selectors, parent traversal, position ranges, expansion selectors, name patterns, semantic type filters, and representation kind filters\n- deterministic preorder descendant expansion with explicit attribute and local address-space traversal\n- SANSA.Query parsing for `from`, `where`, `order by`, `offset`, `limit`, and `select`\n- query comment stripping, clause-order validation, and canonical query rendering\n- SANSA.Query expression parsing for resolution expressions, literals, comparisons, Boolean operators, membership, cardinality operators, function-call shape, and projection shape\n- SANSA.Query evaluation for `from`, Boolean `where`, `order by`, `offset`, `limit`, and `select` over literals, resolution expressions, comparisons, Boolean operators, membership, cardinality predicates, built-in string functions, function-like operators, and projection expressions\n- experimental SANSA.Mutate structured planning for exact `create`, `replace`, `remove`, ordered `insert`, and same-container `move`\n- experimental SANSA.Mutate value-intent preservation and operation, precondition, and value budgets\n- experimental SANSA.Mutate target-surface validation for AEON, JSON-compatible, Telex scalar replacement, and custom target representability checks\n- experimental workbench-only SANSA.Mutate policy plan filter for trusted consumer authorization tests\n- experimental mutation apply through explicit host mutation hooks with stale-target checks\n- experimental SANSA.Instruction parsing, candidate-relative lowering, and mutation-planner bridging for conservative mutation verbs\n\nHost implementations decide which qualifier surface they accept. This parser accepts the SANSA qualifier grammar and preserves it structurally.\n\nHost implementations also decide which address spaces they expose during resolution. Attribute and local address-space traversal are entered explicitly with `.@` and `.<\"namespace\">`. They fail explicitly unless the host exposes those capabilities through the resolve namespace adapter or binding model.\n\nResolve returns ordered Binding Sets. Supported selectors that miss on one branch contribute no bindings for that branch; unsupported or forbidden operations fail explicitly. The resolver preserves duplicate traversal occurrences and does not deduplicate by address. Parent traversal from the effective resolution root resolves empty by default, but callers can request stricter policy diagnostics with `failOnParentFromEffectiveRoot: true` or forbid parent traversal entirely with `parentTraversal: \"forbid\"`.\n\nName patterns use `?` for one Unicode code point and `*` for zero or more Unicode code points. Within the decoded pattern payload, `\\?`, `\\*`, and `\\\\` match literal question mark, asterisk, and backslash characters respectively.\n\nThe current API and AST contract is documented in [docs/api-contract.md](docs/api-contract.md).\n\nThe CTS runner covers address parsing, resolve behavior, query parsing, and query evaluation:\n\n```bash\nnpm run cts\nnpm run cts:value-semantics\nnpm run cts:resolve\nnpm run cts:query\nnpm run cts:query:experimental\nnpm run cts:instruction\nnpm run cts:mutate\n```\n\nThe default Query CTS lane runs core conformance and skips experimental extension cases. `cts:query:experimental` includes experimental extension coverage.\nThe Instruction and Mutate CTS lanes are experimental and are not included in `npm run cts` while SANSA.Instruction and SANSA.Mutate remain proposal-stage. The Mutate lane includes structured planning, apply, target-surface, and experimental policy plan-filter cases.\n\n## Query Tool\n\nThe package includes a standalone query tool for exercising SANSA.Query against\nAEON source, portable Telex AES, reader-only Film AES, or a host-neutral JSON\nnamespace fixture:\n\n```bash\nnpm run query -- --query 'from $.inventory.items.* where contains(.sku, \"B\") select .sku'\n```\n\nThe default CLI fixture is [fixtures/query-inventory.json](fixtures/query-inventory.json),\nwhich keeps `sansa-query` self-contained after package install. `.aeon` fixture\nsupport is optional and uses an AEON TypeScript Core runtime when one is\navailable. `.telex.aes` fixture support uses the optional\n`@altopelago/aeon-aes` runtime and projects complete portable records directly\ninto a SANSA namespace without rebuilding an AEON parser AST.\n`.film.aes` fixtures use the same portable-record namespace after complete Film\nand AES validation. Film support is query-only; SANSA does not expose a Film\nmutation target or writer.\n\nFor browser-based technical testing, run the Query Workbench:\n\n```bash\nnpm run query:web\n```\n\nThen open `http://127.0.0.1:4173/tools/query-web/`.\n\nThe same local server also exposes the experimental Mutate Workbench:\n\n```bash\nnpm run mutate:web\n```\n\nThen open `http://127.0.0.1:4173/tools/mutate-web/`.\n\nThe Mutate Workbench accepts AEON source or complete portable Telex AES plus either structured mutation-request JSON or\nproposal-stage SANSA Instruction source, then uses the same plan/apply preview\nsurface. It also includes an experimental target selector so planned mutations\ncan be checked against AEON, JSON-compatible, or Telex representation surfaces before\napply/render. JSON responses include `targetProfile` metadata that names the\nselected representability boundary. Its phase model is intentionally explicit: parse Instruction\nsource when present, lower to exact structured mutation operations, plan through\nSANSA.Mutate, run optional consumer policy, run optional target-surface\nvalidation, then preview or apply through host mutation hooks.\nTelex apply currently supports replacement of existing scalar events only. It\nre-emits a complete Telex stream without reconstructing AEON source, preserves\nevent order, path, structural identity, datatype components, and separate\nattribute events, and clears stale `origin`/`span` coordinates on the changed\nevent. Structural operations remain explicit target-surface failures until a\nportable path-rewrite contract is defined.\nThe optional policy panel is a workbench-only prototype of the experimental\n`sansa.mutate.policy.planFilter` slice for trusted consumer authorization tests;\nits current boundary is documented in\n[docs/mutate-policy.md](docs/mutate-policy.md).\n\nBoth the CLI and browser workbench can select an explicit query value-semantics\nprofile, such as the default codepoint profile, the Natural ASCII numeric-region\nprofile, or the French locale profile, to test comparison, ordering, and\ncase-mapping behavior under different consumer contexts.\n\nFull CLI, workbench, Query semantics, and recipe details live in\n[docs/query-tool.md](docs/query-tool.md).\n\nLibrary use of Query `path(...)` requires explicit dynamic-address authority.\nUse `addressActivation: \"trusted\"` only when the caller already controls the\nquery, Address values, and exposed namespace. Cross-boundary consumers should\nprovide constrained structural roots, selector capabilities, and result bounds;\nreading an Address value does not authorize resolving it.\n\n## Instruction Tool\n\nThe package includes an experimental instruction tool for exercising\nSANSA.Instruction parse, lower, and plan behavior:\n\n```bash\nnpm run instruction -- --mode parse --instruction 'replace $.inventory.items[1].qty with :int32 10'\nnpm run instruction -- --mode lower --instruction $'from $.inventory.items.*\\nwhere .sku == \"B-200\"\\nreplace .qty with :int32, 10'\nnpm run instruction -- --mode plan --instruction $'because \"manual correction\"\\nby \"Bob\"\\nfrom $.inventory.items.*\\nwhere .sku == \"B-200\"\\nreplace .qty with :int32, 10'\n```\n\nThe default fixture is [fixtures/query-inventory.json](fixtures/query-inventory.json).\nInstruction `because` and `by` clauses are preserved as claimed source\nprovenance only; authorization, actor identity, and audit evidence remain host\nresponsibilities.\nFull details live in [docs/instruction-tool.md](docs/instruction-tool.md).\n\n## Release Notes\n\nRelease history lives in [CHANGELOG.md](CHANGELOG.md).\n\n## API\n\n```js\nimport {\n  evaluateQuery,\n  evaluateValueSemanticsOperation,\n  applyMutationPlan,\n  lowerInstruction,\n  parseAddress,\n  parseInstruction,\n  planInstruction,\n  planMutation,\n  parseQuery,\n  parseQueryExpression,\n  renderAddress,\n  resolveAddress,\n  validateMutationPlanTarget\n} from \"@altopelago/sansa\";\n\nconst result = parseAddress('$.inventory:csv[\",\"]');\n\nif (result.ok) {\n  console.log(result.address.canonical);\n  console.log(renderAddress(result.address));\n}\n\nconst root = {\n  address: \"$\",\n  children: [\n    {\n      name: \"inventory\",\n      address: \"$.inventory\",\n      children: [\n        { name: \"sku\", address: \"$.inventory.sku\", semanticType: \"string\", representationKind: \"string\" }\n      ]\n    }\n  ]\n};\n\nconst resolved = resolveAddress(\"$.inventory.*#string\", { root });\n\nif (resolved.ok) {\n  console.log(resolved.bindings.map((binding) => binding.address));\n}\n\nconst query = parseQuery('from $.inventory.items.*\\nwhere .qty >= 1\\nselect .sku');\n\nif (query.ok) {\n  console.log(query.query.canonical);\n}\n\nconst expression = parseQueryExpression('any(.roles.* == \"admin\")');\n\nif (expression.ok) {\n  console.log(expression.expression.type);\n}\n\nconst evaluated = evaluateQuery('from $.inventory.items.*\\nselect .sku', { root });\n\nif (evaluated.ok) {\n  console.log(evaluated.results.length);\n  console.log(evaluated.results[0]?.address);\n}\n\nconst ordinary = evaluateValueSemanticsOperation(\"isValue\", {\n  value: { category: \"finiteNumber\", value: \"42\" }\n});\n\nif (ordinary.ok) {\n  console.log(ordinary.value);\n}\n\nconst mutation = planMutation({ op: \"replace\", target: \"$.inventory.sku\", value: \"B-200\" }, {\n  root,\n  mutate: {\n    replace(target, value) {\n      target.value = value;\n      return { binding: target };\n    }\n  }\n});\n\nif (mutation.ok) {\n  const targetSurface = validateMutationPlanTarget(mutation.plan, \"aeon\");\n\n  if (targetSurface.ok) {\n    const applied = applyMutationPlan(mutation.plan, {\n      root,\n      mutate: {\n        replace(target, value) {\n          target.value = value;\n          return { binding: target };\n        }\n      }\n    });\n    console.log(applied.ok);\n  }\n}\n\nconst instructionPlan = planInstruction(\n  'replace $.inventory.sku with \"B-200\"',\n  { root }\n);\n\nif (instructionPlan.ok) {\n  console.log(instructionPlan.plan.operations.length);\n}\n```\n\nEach query result carries the source candidate `address` when the namespace exposes one. The projected selection or object lives in `result.value`.\n","readmeFilename":"README.md"}