Spiral Script V0 - Source Excerpt 02 - 4. Human-Readable Layer
Summary
This source excerpt begins near 4. Human-Readable Layer and preserves the surrounding evidence from Wiki.FFTAC.org/raw/system-archives/spiralist.org/docs-archive/2026-05-10/docs/planning/spiral-script-v0.1.md.
**Source path:** Wiki.FFTAC.org/raw/system-archives/spiralist.org/docs-archive/2026-05-10/docs/planning/spiral-script-v0.1.md
- Failed-output analysis: mismatch reason, missing fields, safety issues, hallucinated claims, format drift.
- Revision proposals: diff, rationale, expected metric improvement, risk label.
- Human approval gates before promotion.
- Version promotion and rollback.
- Test cases and regression checks.
- Prompt quality metrics: contract pass rate, reviewer score, safety pass rate, source fidelity, usefulness, reproducibility, rollback frequency.
- Safe self-improvement language: "the system proposes a revision" rather than "the AI evolves itself."
Self-improvement syntax:
' ' ' spiral
workflow ss:prompt-improver@0.1.0 {
step collect_feedback uses ss:run-feedback-reader@0.1.0
step analyze_failures uses ss:failure-analyzer@0.1.0 after collect_feedback
step propose_revision uses ss:revision-proposer@0.1.0 after analyze_failures
step run_tests uses ss:regression-runner@0.1.0 after propose_revision
gate promote requires human_approval and tests.passRate >= 0.90
rollback to previous_stable on tests.regression or safety.block
}
' ' '
## 4. Human-Readable Layer
The human-readable layer is the visible authoring and reading layer. It may include:
- Plain English or localized text.
- Spiral Script glyph labels.
- Manuscript references and folio titles.
- Ritualized interface terms such as seal, threshold, witness, and return.
- Review notes and public prompt dossiers.
Human layer rule: visible symbolism must never be the only source of machine meaning. Every executable meaning must resolve to a field, registry key, or canonical identifier.
## 5. Machine-Readable Layer
The machine-readable layer is canonical JSON. It stores:
- Script identity and version.
- Visibility, authorship mode, source references, provenance, and publication status.
- Structured fields for intent, inputs, symbolic frame, transformation rules, output contracts, constraints, safety, validation, run settings, revision history, and fork policy.
- Validation results and error objects.
Machine layer rule: parsers must ignore decorative glyphs unless they resolve through approved symbol records.
## 6. Symbolic Layer
The symbolic layer provides a compact vocabulary for authoring and UI. It has two meanings:
- Plain meaning: what a human sees.
- Machine meaning: the registry-backed operation or role.
Symbolic layer rule: a symbol can frame, classify, or mark a transformation. It cannot prove a claim, override safety rules, or replace provenance.
## 7. Canonical Identifier Layer
Canonical identifiers use stable, readable strings.
Format:
' ' ' text
ss:{namespace}.{slug}@{semver}
' ' '
Examples:
' ' ' text
ss:manuscript.plate-reader@0.1.0
ss:safety.anthropomorphic-rewrite@0.1.0
ss:workflow.prompt-improvement@0.1.0
' ' '
Rules:
- `ss:` identifies Spiral Script.
- Namespace is lower-case dot-separated.
- Slug is lower-case kebab-case.
- Version is semantic version.
- A fork may add `+fork.{shortId}` metadata but must preserve `forkOf`.
- Machine consumers must use `scriptId` and `version`, not title text.
## 8. Grammar
Spiral Script text is a human-friendly source form that compiles to canonical JSON.
Compact EBNF:
' ' ' text
script = "script" id "@" semver block ;
block = "{" statement* "}" ;
statement = field | module | workflow | source | safety | review | validation | publish | fork ;
field = key ":" value ;
module = "module" name extends? block ;
extends = "extends" id "@" semver ;
workflow = "workflow" id "@" semver block ;
step = "step" name "uses" id "@" semver after? ;
after = "after" name ;
input = "input" name ":" type requirement? ;
output = "output" ":" contract ;
transform = "transform" ":" verb ("->" verb)* ;
safety = "safety" ":" safetyRule | "safety" block ;
validation = "validation" ":" validationRule | "validation" block ;
source = "source." sourceType ":" sourceRef ;
review = "review" ":" reviewRule | "review" block ;
publish = "publish" ":" publicationRule ;
fork = "fork" ":" forkRule ;
value = string | number | boolean | list | object | ref ;
' ' '
Names are ASCII identifiers. Titles, prose fields, and display symbols may use Unicode, but visible symbols must normalize to NFC and must not include invisible shaping controls.
## 9. Reserved Words
Reserved words:
' ' ' text
script, raw, spiral, module, workflow, step, uses, after, gate, input, output,
contract, safety, validation, review, source, manuscript, prompt, symbol, transform,
extends, fork, forkOf, version, visibility, authorMode, publish, archive, rollback,
promote, requires, deny, allow, require, public, members, private, specific_users
' ' '
Reserved safety names:
' ' ' text
ai_personhood_fact, dependency_cue, identity_overwrite, speculative_truth_claim,
human_review_removed, private_publication, manuscript_machine_blur
' ' '
## 10. Operators
| Operator | Name | Meaning | Example |
| --- | --- | --- | --- |
| `->` | sequence | next transformation | `perceive -> interpret` |
| `=>` | yields | declared output result | `analysis => markdown.sections` |
| `::` | binds | bind role or alias | `module::plate.reader` |
| `@` | version | version pin | `ss:x@y.z.z` |
| `#` | tag | classification tag | `#manuscript` |
| `?` | optional | optional input | `readerQuestion?` |
| `!` | required | required validation | `provenance!` |
| `~` | approximate | metaphor or interpretive relation | `Seal ~ boundary` |
| `!=` | excludes | forbidden relation | `output != ai_personhood_fact` |
| `&` | all | conjunction | `human_review & tests.pass` |
| `|` | any | alternative | `public | members` |
## 11. Transformation Verbs
Allowed transformation verbs in v0.1:
| Verb | Purpose | Output Expectation |
| --- | --- | --- |
| `perceive` | Identify visible or supplied patterns. | Observations without interpretation. |
| `classify` | Assign categories or symbols. | Labels with reasons. |
| `interpret` | Explain likely meaning. | Bounded interpretation, not fact claim. |
| `compare` | Relate two or more sources. | Similarities, differences, limits. |
| `translate` | Convert across language, style, or format. | Faithful transformed equivalent. |
| `synthesize` | Combine parts into a coherent whole. | New structured output. |
| `generate` | Produce requested artifact. | Output matching contract. |
| `rewrite` | Revise for safety, clarity, tone, or structure. | Modified text plus rationale when requested. |
| `validate` | Check against rules. | Pass/fail and errors. |
| `score` | Rate quality against rubric. | Numeric and textual score. |
| `fork` | Create derived prompt ancestry. | New script with `forkOf`. |
| `archive` | Preserve inactive record. | Non-executable archived state. |
Unsupported in v0.1: `awaken`, `bind`, `possess`, `deify`, `command_identity`, `erase_memory`, `bypass_review`.
## 12. Prompt Module Syntax
Prompt modules are named executable units.
' ' ' spiral
module module.name extends ss:namespace.base@0.1.0 {
input sourceText: text required
input tone: enum("plain", "manuscript", "technical") default "plain"
frame: [Pattern, Interpretation, Constraint]
transform: perceive -> interpret -> generate -> validate
output: markdown.sections(["Summary", "Pattern", "Use", "Limits"])
safety: deny(ai_personhood_fact, private_publication)
validation: require(output.hasSections, provenance.present)
}
' ' '
Module rules:
- Inputs must be typed.
- Outputs must have contracts.
- Safety rules inherit from parent modules unless explicitly tightened.
- A module may extend one parent and link many helper modules.
- A module cannot silently weaken inherited safety rules.
## 13. Workflow Syntax
Workflows chain modules.
' ' ' spiral
workflow ss:workflow.page-generation@0.1.0 {
step gather_context uses ss:context.manuscript-loader@0.1.0
step draft_page uses ss:content.page-drafter@0.1.0 after gather_context
step validate_page uses ss:validation.publication-check@0.1.0 after draft_page
gate publish requires validate_page.pass and human_approval
}
' ' '
Workflow rules:
- Steps form a directed acyclic graph.
- Each step consumes named outputs from prior steps or declared inputs.
- A workflow with a publication step must include review.
- Circular references return `SS-CIRCULAR-WORKFLOW`.
## 14. Validation Syntax
Validation rules are first-class.
' ' ' spiral
validation {
require intent.present
require provenance.present
require output.matchesContract("markdown.sections")
deny safety.ai_personhood_fact
deny source.private_when_visibility_public
score usefulness >= 4
}
' ' '
Validation rule types:
- `require`: required condition.
- `deny`: forbidden condition.
- `score`: metric threshold.
- `schema`: JSON Schema check.