@semacode/cli 2.1.0 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (154) hide show
  1. package/README.md +107 -4
  2. package/dist/agentContext.d.ts +1 -1
  3. package/dist/agentContextPack.js +6 -1
  4. package/dist/agentContextTipos.d.ts +4 -2
  5. package/dist/agentContextTipos.js +7 -0
  6. package/dist/agentEntryPoints.js +70 -19
  7. package/dist/comandos.js +6 -0
  8. package/dist/discovery/catalog.d.ts +11 -0
  9. package/dist/discovery/catalog.js +521 -0
  10. package/dist/discovery/command.d.ts +11 -0
  11. package/dist/discovery/command.js +226 -0
  12. package/dist/discovery/index.d.ts +5 -0
  13. package/dist/discovery/index.js +8 -0
  14. package/dist/discovery/ranker.d.ts +3 -0
  15. package/dist/discovery/ranker.js +310 -0
  16. package/dist/discovery/redaction.d.ts +2 -0
  17. package/dist/discovery/redaction.js +21 -0
  18. package/dist/discovery/render.d.ts +2 -0
  19. package/dist/discovery/render.js +100 -0
  20. package/dist/discovery/types.d.ts +119 -0
  21. package/dist/discovery/types.js +13 -0
  22. package/dist/execucoesExternas.js +19 -5
  23. package/dist/exemplosOficiais.js +29 -8
  24. package/dist/iaPrompts.d.ts +1 -1
  25. package/dist/iaPrompts.js +3 -0
  26. package/dist/index.d.ts +3 -0
  27. package/dist/index.js +24 -5
  28. package/dist/index.part01.d.ts +1 -1
  29. package/dist/index.part01.js +47 -3
  30. package/dist/index.part06.js +3 -0
  31. package/dist/initTemplatesBase.js +3 -2
  32. package/dist/pipelineConteudo/adapters.d.ts +84 -0
  33. package/dist/pipelineConteudo/adapters.js +449 -0
  34. package/dist/pipelineConteudo/canonical.d.ts +18 -0
  35. package/dist/pipelineConteudo/canonical.js +107 -0
  36. package/dist/pipelineConteudo/command.d.ts +3 -0
  37. package/dist/pipelineConteudo/command.js +572 -0
  38. package/dist/pipelineConteudo/index.d.ts +9 -0
  39. package/dist/pipelineConteudo/index.js +12 -0
  40. package/dist/pipelineConteudo/ledger.d.ts +68 -0
  41. package/dist/pipelineConteudo/ledger.js +732 -0
  42. package/dist/pipelineConteudo/planner.d.ts +12 -0
  43. package/dist/pipelineConteudo/planner.js +366 -0
  44. package/dist/pipelineConteudo/projection.d.ts +16 -0
  45. package/dist/pipelineConteudo/projection.js +57 -0
  46. package/dist/pipelineConteudo/state.d.ts +23 -0
  47. package/dist/pipelineConteudo/state.js +615 -0
  48. package/dist/pipelineConteudo/trust.d.ts +17 -0
  49. package/dist/pipelineConteudo/trust.js +750 -0
  50. package/dist/pipelineConteudo/types.d.ts +331 -0
  51. package/dist/pipelineConteudo/types.js +4 -0
  52. package/dist/profileArtefatoValidadores.d.ts +3 -2
  53. package/dist/profileArtefatoValidadores.js +81 -0
  54. package/dist/profileAuthorTipos.d.ts +4 -3
  55. package/dist/profileCatalogo.d.ts +5 -5
  56. package/dist/profileCatalogo.js +30 -0
  57. package/dist/profileCommand.d.ts +8 -2
  58. package/dist/profileCommand.js +15 -5
  59. package/dist/profileRegras.d.ts +5 -5
  60. package/dist/profileRegras.js +13 -1
  61. package/dist/profileRulePacks.js +68 -0
  62. package/dist/sistemasInterativos/adapterProtocol.d.ts +3 -0
  63. package/dist/sistemasInterativos/adapterProtocol.js +240 -0
  64. package/dist/sistemasInterativos/advancedCatalog.d.ts +5 -0
  65. package/dist/sistemasInterativos/advancedCatalog.js +442 -0
  66. package/dist/sistemasInterativos/autonomy.d.ts +230 -0
  67. package/dist/sistemasInterativos/autonomy.js +753 -0
  68. package/dist/sistemasInterativos/canonical.d.ts +3 -0
  69. package/dist/sistemasInterativos/canonical.js +43 -0
  70. package/dist/sistemasInterativos/catalog.d.ts +116 -0
  71. package/dist/sistemasInterativos/catalog.js +543 -0
  72. package/dist/sistemasInterativos/command.d.ts +7 -0
  73. package/dist/sistemasInterativos/command.js +311 -0
  74. package/dist/sistemasInterativos/controlRun.d.ts +56 -0
  75. package/dist/sistemasInterativos/controlRun.js +391 -0
  76. package/dist/sistemasInterativos/evidence.d.ts +5 -0
  77. package/dist/sistemasInterativos/evidence.js +306 -0
  78. package/dist/sistemasInterativos/experienceIr.d.ts +12 -0
  79. package/dist/sistemasInterativos/experienceIr.js +895 -0
  80. package/dist/sistemasInterativos/experienceIrSemantics.d.ts +30 -0
  81. package/dist/sistemasInterativos/experienceIrSemantics.js +368 -0
  82. package/dist/sistemasInterativos/experienceIrTypes.d.ts +370 -0
  83. package/dist/sistemasInterativos/experienceIrTypes.js +5 -0
  84. package/dist/sistemasInterativos/extensionCommand.d.ts +391 -0
  85. package/dist/sistemasInterativos/extensionCommand.js +383 -0
  86. package/dist/sistemasInterativos/index.d.ts +19 -0
  87. package/dist/sistemasInterativos/index.js +22 -0
  88. package/dist/sistemasInterativos/operations.d.ts +40 -0
  89. package/dist/sistemasInterativos/operations.js +1167 -0
  90. package/dist/sistemasInterativos/operationsTypes.d.ts +297 -0
  91. package/dist/sistemasInterativos/operationsTypes.js +11 -0
  92. package/dist/sistemasInterativos/planner.d.ts +2 -0
  93. package/dist/sistemasInterativos/planner.js +159 -0
  94. package/dist/sistemasInterativos/portability.d.ts +164 -0
  95. package/dist/sistemasInterativos/portability.js +539 -0
  96. package/dist/sistemasInterativos/render.d.ts +3 -0
  97. package/dist/sistemasInterativos/render.js +179 -0
  98. package/dist/sistemasInterativos/temporal.d.ts +183 -0
  99. package/dist/sistemasInterativos/temporal.js +543 -0
  100. package/dist/sistemasInterativos/types.d.ts +215 -0
  101. package/dist/sistemasInterativos/types.js +4 -0
  102. package/dist/sistemasInterativos/validator.d.ts +2 -0
  103. package/dist/sistemasInterativos/validator.js +305 -0
  104. package/docs/README.md +9 -0
  105. package/docs/ai-integration.md +7 -1
  106. package/docs/ai-workflow.md +5 -4
  107. package/docs/commands.md +43 -1
  108. package/docs/descoberta-capacidades.md +106 -0
  109. package/docs/documentation.md +11 -2
  110. package/docs/pipeline-conteudo.md +246 -0
  111. package/docs/profiles.md +11 -2
  112. package/docs/sistemas-interativos.md +381 -0
  113. package/docs/testing.md +11 -2
  114. package/exemplos/pipeline-conteudo/README.md +44 -0
  115. package/exemplos/pipeline-conteudo/alvos.json +23 -0
  116. package/exemplos/pipeline-conteudo/definicao.json +136 -0
  117. package/exemplos/profile_simulation.sema +211 -0
  118. package/exemplos/sistemas-interativos/README.md +100 -0
  119. package/exemplos/sistemas-interativos/advanced/acceptance-context-evaluate-valid.json +5 -0
  120. package/exemplos/sistemas-interativos/advanced/acceptance-lock-valid.json +16 -0
  121. package/exemplos/sistemas-interativos/advanced/asset-provenance-valid.json +32 -0
  122. package/exemplos/sistemas-interativos/advanced/autonomy-repair-valid.json +93 -0
  123. package/exemplos/sistemas-interativos/advanced/control-run-definition-valid.json +78 -0
  124. package/exemplos/sistemas-interativos/advanced/control-run-valid.json +27 -0
  125. package/exemplos/sistemas-interativos/advanced/distributed-workers-valid.json +79 -0
  126. package/exemplos/sistemas-interativos/advanced/editor-state-valid.json +42 -0
  127. package/exemplos/sistemas-interativos/advanced/engine-snapshot-after-valid.json +32 -0
  128. package/exemplos/sistemas-interativos/advanced/engine-snapshot-before-valid.json +23 -0
  129. package/exemplos/sistemas-interativos/advanced/job-orchestration-valid.json +39 -0
  130. package/exemplos/sistemas-interativos/advanced/multimodal-evidence-valid.json +46 -0
  131. package/exemplos/sistemas-interativos/advanced/multiplayer-authority-valid.json +39 -0
  132. package/exemplos/sistemas-interativos/advanced/playtest-fuzz-valid.json +37 -0
  133. package/exemplos/sistemas-interativos/advanced/portability-valid.json +104 -0
  134. package/exemplos/sistemas-interativos/advanced/temporal-evidence-valid.json +27 -0
  135. package/exemplos/sistemas-interativos/advanced/temporal-valid.json +118 -0
  136. package/exemplos/sistemas-interativos/experience-ir-valid.json +459 -0
  137. package/exemplos/sistemas-interativos/game-2d.json +83 -0
  138. package/exemplos/sistemas-interativos/game-3d-human.json +81 -0
  139. package/exemplos/sistemas-interativos/game-pixel-16-bit.json +97 -0
  140. package/exemplos/sistemas-interativos/game-pixel-8-bit.json +94 -0
  141. package/exemplos/sistemas-interativos/game-xr-human.json +80 -0
  142. package/exemplos/sistemas-interativos/hybrid-2-5d.json +108 -0
  143. package/exemplos/sistemas-interativos/protocol-mutating-rollback-valid.json +75 -0
  144. package/exemplos/sistemas-interativos/protocol-read-only-valid.json +58 -0
  145. package/exemplos/sistemas-interativos/simulation-2d-controlled.json +97 -0
  146. package/exemplos/sistemas-interativos/simulation-3d-calibrated-autonomous.json +141 -0
  147. package/exemplos/sistemas-interativos/simulation-headless-autonomous-batch.json +112 -0
  148. package/exemplos/sistemas-interativos/simulation-pixel-16-bit.json +103 -0
  149. package/exemplos/sistemas-interativos/simulation-text-controlled.json +95 -0
  150. package/node_modules/@sema/gerador-lua/dist/index.js +78 -4
  151. package/node_modules/@sema/gerador-lua/dist/index.js.map +1 -1
  152. package/node_modules/@sema/gerador-php/dist/index.js +8 -0
  153. package/node_modules/@sema/gerador-php/dist/index.js.map +1 -1
  154. package/package.json +8 -1
@@ -0,0 +1,381 @@
1
+ # AI-native Interactive Systems
2
+
3
+ Sema Interactive is the declarative control plane for games, simulations, and
4
+ hybrid interactive systems. The same core covers 3D, 2.5D, 2D, text, retro
5
+ 8/16-bit presentation, XR, and headless execution.
6
+
7
+ It does not embed a game engine or silently control an editor. Sema validates
8
+ definitions, calculates required capabilities, selects compatible external
9
+ adapter descriptors, expands pipelines into evidence-bearing stages, and
10
+ derives non-authoritative local results. An explicitly integrated external
11
+ runner must perform any engine, editor, plug-in, build, verifier, or worker
12
+ operation.
13
+
14
+ The public CLI is a read-only control plane. It does **not** detect, probe,
15
+ launch, install, or control Unreal, Unity, Godot, Blender, PICO-8, TIC-80,
16
+ LÖVE, a browser runtime, a custom engine, a plug-in, or a distributed worker.
17
+ Catalog presence means only that a descriptor exists; it is not runtime
18
+ availability evidence.
19
+
20
+ ## The dimensions are independent
21
+
22
+ An interactive definition separates concerns that are often incorrectly mixed:
23
+
24
+ | Axis | Examples |
25
+ | --- | --- |
26
+ | Kind | `GAME`, `SIMULATION`, `HYBRID` |
27
+ | Spatial model | `NON_SPATIAL`, `TWO_D`, `TWO_POINT_FIVE_D`, `THREE_D` |
28
+ | Render mode | `HEADLESS`, `TEXT`, `VISUAL`, `XR` |
29
+ | Visual profile | `NONE`, `PIXEL_8_BIT`, `PIXEL_16_BIT`, `RASTER`, `VECTOR`, `STYLIZED`, `REALISTIC` |
30
+ | Fidelity | `ARCADE`, `STYLIZED`, `SYSTEMIC`, `REALISTIC`, `CALIBRATED` |
31
+ | Control | human, scripted, AI, hybrid, autonomous, or uncontrolled/emergent |
32
+ | Time | fixed step, variable step, turn based, event driven, or accelerated |
33
+ | Determinism | strict, seeded, best effort, or stochastic |
34
+
35
+ `PIXEL_8_BIT` and `PIXEL_16_BIT` are visual/technical profiles, not spatial
36
+ dimensions or lesser product classes. A 16-bit economic simulation and a 3D
37
+ flight simulation use the same world/state/time/evidence core with different
38
+ budgets and adapters.
39
+
40
+ ## Core commands
41
+
42
+ ```bash
43
+ sema interativo capabilities --json
44
+ sema interativo schema --json
45
+ sema interativo pipelines --json
46
+ sema interativo adapters --spatial-model TWO_D --render-mode VISUAL --json
47
+ sema interativo validar exemplos/sistemas-interativos/game-pixel-16-bit.json --json
48
+ sema interativo planejar exemplos/sistemas-interativos/game-pixel-16-bit.json --json
49
+ sema interativo validar-evidencias <definition.json> [--plano-arquivo <plan.json>] --bundle-arquivo <bundle.json> --json
50
+ sema interativo status <definition.json> [--plano-arquivo <plan.json>] --bundle-arquivo <bundle.json> --json
51
+ sema interativo validar-protocolo <adapter-run.json> --json
52
+ ```
53
+
54
+ Every command above is local and declarative. Responses report
55
+ `executed: false` and `workspaceMutated: false`. The CLI does not open an
56
+ engine, editor, browser runtime, or custom simulator.
57
+
58
+ `--evidencias-arquivo` is accepted as an alias for `--bundle-arquivo`. When
59
+ `--plano-arquivo` is omitted, the CLI recomputes the deterministic plan and
60
+ still rejects any bundle whose definition or plan digest does not match.
61
+
62
+ `schema` is the stable, read-only machine contract for definition generation.
63
+ It exposes required fields, supported enum values, cross-field constraints,
64
+ the capability matrix, and canonical example paths. Its advanced command map
65
+ links every positional/option surface to input and output schemas; each data
66
+ schema exposes required top-level fields and official fixtures. Each subcommand
67
+ has an explicit argument allowlist: unknown flags, duplicate semantic flags,
68
+ missing values, and invalid enum values fail closed instead of producing an
69
+ empty successful result.
70
+
71
+ ## Advanced read-only commands
72
+
73
+ The advanced command surface exposes the same pure validators and planners to
74
+ AI agents. File-based commands read JSON, every command returns structured JSON,
75
+ and engine, editor, process, plug-in, and worker inspection remains an external
76
+ integration responsibility.
77
+
78
+ Experience IR:
79
+
80
+ ```bash
81
+ sema interativo validar-ir <experience-ir.json> --json
82
+ sema interativo indexar-ir <experience-ir.json> --json
83
+ sema interativo consultar-ir <experience-ir.json> --semantic-id <id> --json
84
+ sema interativo chunk-ir <experience-ir.json> --semantic-id <id> [--raso] --json
85
+ sema interativo descrever-ir --json
86
+ ```
87
+
88
+ Operational snapshots, provenance, jobs, acceptance, and multimodal evidence:
89
+
90
+ ```bash
91
+ sema interativo validar-engine-snapshot <snapshot.json> --json
92
+ sema interativo diff-engine-snapshots <before.json> <after.json> --json
93
+ sema interativo validar-asset-provenance <provenance.json> --json
94
+ sema interativo validar-editor-state <editor-state.json> --json
95
+ sema interativo planejar-jobs <jobs.json> --json
96
+ sema interativo validar-acceptance <acceptance-lock.json> --json
97
+ sema interativo operar-acceptance <acceptance-lock.json> --operation <VALIDATE|EVALUATE|INVALIDATE> --context-file <context.json> --json
98
+ sema interativo validar-multimodal <evidence.json> --json
99
+ ```
100
+
101
+ Time, autonomy, portability, and distributed work:
102
+
103
+ ```bash
104
+ sema interativo validar-temporal <temporal-contract.json> --json
105
+ sema interativo validar-evidencia-temporal <temporal-contract.json> --bundle-arquivo <temporal-evidence.json> --json
106
+ sema interativo validar-autonomia <repair-cycle.json> --json
107
+ sema interativo validar-playtest-fuzz <playtest-fuzz.json> --json
108
+ sema interativo validar-multiplayer <authority-model.json> --json
109
+ sema interativo analisar-portabilidade <portability-plan.json> --json
110
+ sema interativo validar-workers <distributed-jobs.json> --json
111
+ ```
112
+
113
+ These commands validate descriptions and derive plans, diffs, indexes, queries,
114
+ chunks, eligibility, or assignments. They do not perform the described work.
115
+
116
+ `sema interativo schema --json` publishes distinct input and output shapes for
117
+ all 20 extension commands. The advertised multimodal input includes claim and
118
+ producer/verifier bindings; autonomy includes cycle and acceptance-lock fields;
119
+ and `jobOrchestrationPlan` exposes `requestDigest`, `planDigest`, and an ordered
120
+ `queue` whose entries are the declared job assignments. Result shapes are
121
+ checked against the official fixtures, and every command publishes
122
+ `outputTargets` path segments from the payload root, so an agent never has to
123
+ reuse an input shape or guess where a validator's output lives.
124
+
125
+ ## Bound control runs
126
+
127
+ `validar-control-run` is the fail-closed bridge from a planned pipeline to one
128
+ specific advanced validator invocation. It binds a strict manifest to the
129
+ definition digest, recomputed canonical plan, selected pipeline descriptor,
130
+ validation contract, schema-declared input digests, evidence, producer and
131
+ verifier identity, and the exact validator result. The CLI reruns the selected
132
+ pure validator and rejects a result, contract, input, evidence, or pipeline
133
+ borrowed from another run.
134
+
135
+ ```bash
136
+ sema interativo validar-control-run <control-run.json> \
137
+ --definition-arquivo <definition.json> \
138
+ --plano-arquivo <plan.json> \
139
+ --contrato-arquivo <validation-contract.json> \
140
+ --entrada-arquivo <input.json> \
141
+ [--entrada-auxiliar-arquivo <supporting-input.json>] \
142
+ --evidencia-arquivo <evidence.json> \
143
+ --resultado-arquivo <result.json> \
144
+ --json
145
+ ```
146
+
147
+ This proves deterministic local binding only. A valid control run still returns
148
+ `completed: false`, `authoritative: false`, and
149
+ `awaitingExternalAttestation: true`; it does not prove that an engine, editor,
150
+ worker, verifier, or external adapter actually ran.
151
+
152
+ ## Experience IR
153
+
154
+ Experience IR is the engine-neutral semantic substrate below the advanced
155
+ pipelines. Version `sema.experience-ir/v1` models 20 kinds of project, world,
156
+ scene, entity, component, transform, camera, light, material, texture, audio,
157
+ physics, constraint, animation, VFX, timeline, input, save, network, and build
158
+ objects. Stable semantic IDs and explicit references make the graph queryable
159
+ without relying on engine-specific object paths.
160
+
161
+ The v1 kind set remains unchanged. Eight engine-neutral concepts use optional,
162
+ typed semantic roles in their natural containers, so existing v1 documents
163
+ remain valid while newer documents can expose the concepts explicitly:
164
+
165
+ | Semantic role | Typed v1 representation |
166
+ | --- | --- |
167
+ | `LEVEL` | `SCENE.semanticRole` |
168
+ | `PIVOT` | `TRANSFORM.semanticRole` |
169
+ | `COLLIDER` | `PHYSICS.colliders[]` |
170
+ | `EMITTER` | `VFX.emitters[]` |
171
+ | `TRACK` | `TIMELINE.tracks[].semanticRole` |
172
+ | `CLIP` | `TIMELINE.tracks[].clips[]` |
173
+ | `EVENT` | `TIMELINE.tracks[].events[]` |
174
+ | `GAME_STATE` | `SAVE.semanticRole` |
175
+
176
+ `descrever-ir` publishes this mapping as
177
+ `sema.experience-ir.semantic-roles/v1`. Index and chunk entries expose their
178
+ canonical `semanticRoles`, while node `kind` remains one of the original 20.
179
+ Typed clips participate in reference validation and dependency closure.
180
+
181
+ The IR declares units and coordinate systems, records asset provenance, and
182
+ uses content-addressed digests for deterministic indexing and chunking. JSON is
183
+ the native canonical serialization. CBOR is an explicitly external codec path;
184
+ the CLI does not pretend to encode it. Indexing, lookup, and dependency-aware
185
+ chunks are in-memory read-only operations. They do not import assets, convert a
186
+ project, materialize a scene, or execute a build.
187
+
188
+ Validation also rejects sensitive values under neutral keys, including private
189
+ keys, Bearer credentials, and common `sk`, `ghp`, or `github_pat` token forms,
190
+ as well as credential-bearing URI queries such as `access_token`, `api_key`,
191
+ `signature`, or `X-Amz-*`, without echoing the value or caller-controlled key
192
+ path. Entity and transform
193
+ parent graphs must be acyclic. Network nodes apply cross-field policy:
194
+ `OFFLINE` means `NONE`, no replicated IDs, and tick zero; `CLIENT_SERVER`
195
+ requires `SERVER`; `PEER_TO_PEER` accepts `OWNER` or `DISTRIBUTED`; and
196
+ `LOCKSTEP` requires `DISTRIBUTED`. Every online mode requires declared
197
+ replication and a positive integer tick rate.
198
+
199
+ ## P0, P1, and P2 coverage
200
+
201
+ The advanced surface is grouped by operational responsibility, not rendering
202
+ style:
203
+
204
+ | Priority | Covered responsibilities |
205
+ | --- | --- |
206
+ | P0 — represent and observe | Experience IR; semantic engine snapshots and diffs; asset origin, license, hashes, transforms, and derivatives; editor-state descriptors; multimodal evidence descriptors; job budgets, locks, heartbeats, checkpoints, resume tokens, and recovery; artifact/time-bound acceptance locks. |
207
+ | P1 — validate behavior over time | 4D phases, tracks, clips, and invariants; shots and camera visibility; collision, attachment, and separation relations; flicker, ghosting, popping, exposure, and jitter QA; materialization, clean-install, launch, and smoke-playtest requirements; target hardware budgets. |
208
+ | P2 — diagnose, scale, and migrate | `diagnose -> propose -> simulate -> prove` repair cycles with safe rollback; bounded bots, fuzzing, and save/load recovery; explicit multiplayer authority and reconnect rules; versioned engine migration and cross-engine portability with declared losses; distributed worker DAGs with capabilities, leases, budgets, and checkpoints. |
209
+
210
+ All three groups apply to 3D, 2.5D, 2D, 8-bit, 16-bit, text, XR, and headless
211
+ games or simulations. A visual profile changes constraints and evidence needs;
212
+ it does not switch to a weaker governance model.
213
+
214
+ ## Canonical pipelines
215
+
216
+ The canonical catalog exposes **35 unique pipelines** and **28 unique external
217
+ adapter descriptors**. Pipelines are reusable goals rather than one workflow
218
+ per rendering style.
219
+
220
+ Core pipelines:
221
+
222
+ - `interactive.prototype`
223
+ - `interactive.playtest`
224
+ - `interactive.package`
225
+ - `interactive.release`
226
+ - `interactive.replay`
227
+ - `interactive.calibrate`
228
+ - `interactive.safety`
229
+ - `game.balance`
230
+ - `game.progression`
231
+ - `game.multiplayer`
232
+ - `simulation.scenario`
233
+ - `simulation.batch_run`
234
+ - `simulation.calibrate`
235
+ - `simulation.validate`
236
+ - `simulation.safety`
237
+
238
+ P0/P1/P2 pipelines:
239
+
240
+ - `interactive.experience_ir`
241
+ - `interactive.observe`
242
+ - `interactive.asset_provenance`
243
+ - `interactive.editor_state`
244
+ - `interactive.evidence_capture`
245
+ - `interactive.job_recovery`
246
+ - `interactive.acceptance_lock`
247
+ - `interactive.temporal_validate`
248
+ - `interactive.shot_validate`
249
+ - `interactive.physics_validate`
250
+ - `interactive.temporal_qa`
251
+ - `interactive.clean_install_smoke`
252
+ - `interactive.hardware_budget`
253
+ - `interactive.autonomous_repair`
254
+ - `interactive.bot_playtest`
255
+ - `interactive.state_fuzz`
256
+ - `interactive.multiplayer_authority`
257
+ - `interactive.engine_migration`
258
+ - `interactive.portability`
259
+ - `interactive.distributed_jobs`
260
+
261
+ Spatial model, render mode, and visual profile influence capabilities, budgets,
262
+ evidence, and adapter compatibility. They do not decide the workflow goal.
263
+ `THREE_D + HEADLESS` is therefore valid, while `XR` requires `THREE_D`.
264
+
265
+ ## Adapter boundary
266
+
267
+ Adapter descriptors represent runtime, editor, asset, build, telemetry,
268
+ observation, IR, autonomy, portability, or distributed-job capabilities. They
269
+ describe compatibility; they do not prove that an engine, editor, plug-in, or
270
+ worker is installed, reachable, or running.
271
+
272
+ The protocol model uses a read-only observation prefix:
273
+
274
+ ```text
275
+ DETECT -> PROBE -> SNAPSHOT -> PLAN
276
+ ```
277
+
278
+ Those names describe phases that an external adapter must implement; the local
279
+ CLI does not perform `DETECT` or `PROBE`. Read-only adapters continue with
280
+ `VALIDATE -> EVIDENCE`. Mutating adapters add `APPLY` and must support
281
+ `ROLLBACK`:
282
+
283
+ ```text
284
+ DETECT -> PROBE -> SNAPSHOT -> PLAN -> APPLY -> VALIDATE -> EVIDENCE
285
+ \-> ROLLBACK on failure
286
+ ```
287
+
288
+ Stable semantic target IDs bind every phase. A failed external mutation without
289
+ rollback evidence is a blocking result.
290
+
291
+ The descriptor catalog includes general targets for Unreal, Unity, Godot,
292
+ Blender, web canvas, LÖVE, PICO-8, TIC-80, headless runtimes, simulation
293
+ runners, validators, telemetry, assets, builds, operational observers, IR,
294
+ autonomy, portability, and distributed jobs. These are compatibility
295
+ descriptors, not bundled integrations, probes, detections, or installation
296
+ claims.
297
+
298
+ Planning is provider-aware. `adapterTargets` is an explicit composition, not a
299
+ decorative preference: every expanded stage capability must be supplied by at
300
+ least one selected compatible descriptor. An empty or partial selection
301
+ produces a blocked plan with deterministic candidate and
302
+ recommended-composition output. A telemetry descriptor cannot stand in for an
303
+ executor, and a generic headless descriptor cannot claim packaging capabilities
304
+ it does not declare.
305
+
306
+ ## Evidence and operational truth
307
+
308
+ Pipeline stages declare exact evidence types. Examples include runtime boot,
309
+ first input, loop completion, failure state, deterministic replay, calibration,
310
+ tolerance comparison, package creation, packaged launch, smoke execution, and
311
+ rollback observation.
312
+
313
+ Compilation does not prove playability. Opening an editor does not prove a
314
+ simulation is valid. An editor playtest does not prove a packaged build. A
315
+ runner saying “success” does not replace observed evidence.
316
+
317
+ The portable evidence bundle in v1 is explicitly non-authoritative. It
318
+ validates binding, digests, stage coverage, stable IDs, non-empty observation
319
+ data, and the producing adapter ID/version against the selected provider for
320
+ each stage. High-assurance environments must additionally provide signed
321
+ envelopes, quorum, anti-replay state, and externally retained checkpoints
322
+ through an appropriate trust/ledger layer. Sema does not label a local JSON file
323
+ as a strong trust boundary.
324
+
325
+ When all local structural checks and supplied observation records pass, status
326
+ is `STRUCTURALLY_COMPLETE`. This is **not authoritative completion**. It means
327
+ only that local structural coverage is complete; it deliberately keeps
328
+ `completed: false`, `authoritative: false`, and
329
+ `awaitingExternalAttestation: true`. It does not prove that an engine ran, an
330
+ editor was inspected, a plug-in existed, a worker accepted a job, a package
331
+ launched, or an external observer attested the result.
332
+
333
+ ## Semantic budget split plan
334
+
335
+ The current operational facade remains compatible, but three governed artifacts
336
+ have crossed the planning threshold: `operations.ts` has 1,112 lines,
337
+ `sistemas_interativos_operacao.sema` has 304 lines, and the installed-package
338
+ smoke `scripts/testar-pacote-cli-publico.mjs` has 1,009 lines. Before any of
339
+ them reaches its blocking limit, split by responsibility as follows:
340
+
341
+ - move engine snapshots, semantic diffs, asset provenance, and editor-state
342
+ observation into `engineObservation.ts`;
343
+ - move queues, locks, budgets, leases, checkpoints, and recovery planning into
344
+ `jobOrchestration.ts`;
345
+ - move acceptance locks, invalidation, and multimodal claim evidence into
346
+ `acceptanceEvidence.ts`;
347
+ - keep `operations.ts` as the stable re-export facade while callers migrate;
348
+ - split the contract into `sistemas_interativos_observacao_engine.sema`,
349
+ `sistemas_interativos_orquestracao_jobs.sema`, and
350
+ `sistemas_interativos_acceptance_evidencias.sema`, with all three contracts
351
+ linked to the shared facade and their actual implementation files;
352
+ - split the installed-package smoke into helpers for public-boundary security,
353
+ Codex bootstrap, content-pipeline compatibility, interactive systems, and
354
+ generated toolchains, while retaining the current script as the stable
355
+ orchestrator and preserving one end-to-end isolated installation.
356
+
357
+ This is a responsibility split, not a numbered-file workaround. Existing
358
+ exports, schema versions, fixtures, digests, and fail-closed behavior must remain
359
+ backward compatible through the migration.
360
+
361
+ ## Fidelity rules
362
+
363
+ Visual realism and model validity are separate. A `REALISTIC` or `CALIBRATED`
364
+ simulation must declare reference data, units, calibration method, tolerances,
365
+ uncertainty, and telemetry. A photorealistic scene without those items is only
366
+ photorealistic, not a validated simulation.
367
+
368
+ Strict or seeded determinism requires a seed, snapshots, event log, reproducible
369
+ step model, and replay result digest. Autonomous or uncontrolled systems require
370
+ stopping criteria, boundaries, and safety evidence.
371
+
372
+ ## Examples
373
+
374
+ The fixtures under `exemplos/sistemas-interativos/` deliberately cover opposing
375
+ cases: human-controlled retro games, 2D simulations, 3D calibrated simulations,
376
+ and autonomous headless batch execution. The `advanced/` fixtures mirror the
377
+ public schemas for IR-adjacent operations, temporal validation, autonomy,
378
+ multiplayer authority, portability, distributed jobs, and fully bound control
379
+ runs. They are synthetic validation inputs, not captured runtime evidence. The coverage matrix proves
380
+ that kind, spatial model, render mode, visual profile, control, fidelity, and
381
+ runtime are composable rather than hardcoded around one showcase project.
package/docs/testing.md CHANGED
@@ -9,6 +9,8 @@ npm run build
9
9
  npm run status:check
10
10
  npm run repo:verificar-publico
11
11
  npm run plugin:testar-codex
12
+ npm run cli:empacotar-publica
13
+ npm run cli:testar-pacote-publico
12
14
  node pacotes/cli/dist/index.js --help
13
15
  node pacotes/cli/dist/index.js --version
14
16
  node pacotes/cli/dist/index.js resumo exemplos/calculadora.sema --micro --json
@@ -26,8 +28,15 @@ encoding in every published document. The plugin smoke must validate the repo
26
28
  marketplace, manifest version, installed skill copy, and absence of Sema MCP.
27
29
  After push and npm publication, `npm run release:verificar-distribuicao` must
28
30
  repeat that installation from the remote `gerlanss/Sema` marketplace and prove
29
- that GitHub HEAD, the installed skill, and npm 2.1.0 all describe the same
30
- release.
31
+ that GitHub HEAD, the installed skill, and the manifest-declared npm version
32
+ all describe the same release.
33
+
34
+ The local public-package smoke installs the generated tarball in an isolated
35
+ sandbox. It must import the root API without executing the CLI, materialize
36
+ nested interactive examples, and execute discovery, interactive schema,
37
+ definition validation, planning, and adapter-protocol validation through the
38
+ installed binary. Passing this smoke proves the local tarball only; it does not
39
+ mean that npm or a GitHub release was published.
31
40
 
32
41
  Native generator evidence is mandatory when changing C#/.NET or C++ support.
33
42
  The `dotnet` smoke must compile and execute through the local .NET SDK. The
@@ -0,0 +1,44 @@
1
+ # Content pipeline example
2
+
3
+ This fixture proves that the pipeline core is independent from a platform,
4
+ brand, or media type. One definition creates a global editorial core and two
5
+ isolated target branches: a long-form document and a spoken audio episode.
6
+ The same AI-native plan can add any number of channels and formats without
7
+ making this experience the only delivery path.
8
+
9
+ Definition v1 declares exactly one output per stage. Each stage also selects an
10
+ `adapterPolicy`: `NONE`, `CONSTRAINTS`, or `CONFIRMATION`. Constraint gates are
11
+ satisfied only by independently signed observations bound to the produced
12
+ artifact, including an independently observed media type; producer metadata
13
+ is not evidence of its own correctness.
14
+
15
+ ```bash
16
+ sema conteudo validar exemplos/pipeline-conteudo/definicao.json --json
17
+ sema conteudo planejar exemplos/pipeline-conteudo/definicao.json --alvos-arquivo exemplos/pipeline-conteudo/alvos.json --json
18
+ ```
19
+
20
+ The example intentionally contains no private keys, signed policy, trust pins,
21
+ ledger checkpoint, or signed events. In a live run, an authorized policy
22
+ authority must sign a policy bound to the execution and complete target set
23
+ through `runId` and `targetSetDigest`, with explicit `issuedAt` and `expiresAt`
24
+ authorization bounds. Every event must be recorded within that interval, and
25
+ every append also supplies that policy envelope. Keep the
26
+ trust-root digest, current `revocationDigest`, and
27
+ required `expectedHead` outside the runner-controlled workspace. Generate
28
+ events in independently controlled producer, evaluator, and adapter processes;
29
+ never commit production private keys to a Sema workspace. The adapter's
30
+ `requiredMetadata + optionalMetadata` is the exact scalar public allowlist;
31
+ artifact metadata is unavailable in v1. The runner resolves credentials
32
+ externally from a strict `account:<alias>` reference.
33
+
34
+ Every gate declares separate deterministic-attester and semantic-AI quorums.
35
+ Use `content.evidence.attest:<evidenceType>` for ordinary attestations. Adapter
36
+ observations use the stricter
37
+ `content.adapter.attest:<adapterId>@<version>:<evidenceType>` capability and
38
+ signed adapter/version binding; a generic receipt capability is intentionally
39
+ insufficient.
40
+
41
+ The runner executes and resumes work from Sema's derived `nextActions`. It does
42
+ not calculate verdicts or edit completion state. Operational conditions remain
43
+ separate from gate verdicts, and every generated manifest is a non-authoritative
44
+ projection of the canonical ledger. There is no native human-review fallback.
@@ -0,0 +1,23 @@
1
+ [
2
+ {
3
+ "targetId": "documento-principal",
4
+ "adapterId": "destination.document",
5
+ "accountScope": "account:publisher.site-a",
6
+ "formatProfileId": "long-form",
7
+ "locale": "pt-BR",
8
+ "metadata": {
9
+ "title": "Exemplo de conteúdo multiformato"
10
+ }
11
+ },
12
+ {
13
+ "targetId": "episodio-audio",
14
+ "adapterId": "destination.audio-feed",
15
+ "accountScope": "account:publisher.feed-a",
16
+ "formatProfileId": "spoken-episode",
17
+ "locale": "pt-BR",
18
+ "metadata": {
19
+ "title": "Exemplo de conteúdo multiformato",
20
+ "description": "A mesma intenção editorial em um destino de áudio independente."
21
+ }
22
+ }
23
+ ]
@@ -0,0 +1,136 @@
1
+ {
2
+ "schemaVersion": "sema.content.pipeline/v1",
3
+ "pipelineId": "conteudo-multidestino-exemplo",
4
+ "version": "1.0.0",
5
+ "stages": [
6
+ {
7
+ "stageId": "pauta",
8
+ "capability": "content.topic.plan",
9
+ "scope": "GLOBAL",
10
+ "adapterPolicy": "NONE",
11
+ "dependsOn": [],
12
+ "produces": ["briefing-editorial"],
13
+ "gateIds": []
14
+ },
15
+ {
16
+ "stageId": "pesquisa",
17
+ "capability": "content.research.collect",
18
+ "scope": "GLOBAL",
19
+ "adapterPolicy": "NONE",
20
+ "dependsOn": ["pauta"],
21
+ "produces": ["dossie-fontes"],
22
+ "gateIds": []
23
+ },
24
+ {
25
+ "stageId": "conteudo-mestre",
26
+ "capability": "content.master.compose",
27
+ "scope": "GLOBAL",
28
+ "adapterPolicy": "NONE",
29
+ "dependsOn": ["pesquisa"],
30
+ "produces": ["conteudo-mestre"],
31
+ "gateIds": ["qa-mestre"]
32
+ },
33
+ {
34
+ "stageId": "adaptacao",
35
+ "capability": "content.target.adapt",
36
+ "scope": "POR_ALVO",
37
+ "adapterPolicy": "CONSTRAINTS",
38
+ "dependsOn": ["conteudo-mestre"],
39
+ "produces": ["conteudo-adaptado"],
40
+ "gateIds": ["qa-destino"]
41
+ },
42
+ {
43
+ "stageId": "entrega",
44
+ "capability": "content.target.deliver",
45
+ "scope": "POR_ALVO",
46
+ "adapterPolicy": "CONFIRMATION",
47
+ "dependsOn": ["adaptacao"],
48
+ "produces": ["confirmacao-entrega"],
49
+ "gateIds": ["confirmacao-externa"]
50
+ }
51
+ ],
52
+ "gates": [
53
+ {
54
+ "gateId": "qa-mestre",
55
+ "stageId": "conteudo-mestre",
56
+ "scope": "GLOBAL",
57
+ "evaluationMode": "IA_ESPECIALIZADA",
58
+ "requiredEvidence": ["artifact.digest.observed"],
59
+ "evaluatorCapabilities": ["content.qa.factual", "content.qa.editorial"],
60
+ "minAttestationsPerEvidence": 1,
61
+ "minDistinctAttesterControlDomains": 1,
62
+ "minApprovals": 2,
63
+ "minDistinctControlDomains": 2,
64
+ "producerDisjoint": true,
65
+ "rejectionIsBinding": true,
66
+ "rubricDigest": "sha256:1111111111111111111111111111111111111111111111111111111111111111"
67
+ },
68
+ {
69
+ "gateId": "qa-destino",
70
+ "stageId": "adaptacao",
71
+ "scope": "POR_ALVO",
72
+ "evaluationMode": "HIBRIDA",
73
+ "requiredEvidence": ["adapter.constraints.passed"],
74
+ "evaluatorCapabilities": ["content.qa.target-fit"],
75
+ "minAttestationsPerEvidence": 1,
76
+ "minDistinctAttesterControlDomains": 1,
77
+ "minApprovals": 1,
78
+ "minDistinctControlDomains": 1,
79
+ "producerDisjoint": true,
80
+ "rejectionIsBinding": true,
81
+ "rubricDigest": "sha256:2222222222222222222222222222222222222222222222222222222222222222"
82
+ },
83
+ {
84
+ "gateId": "confirmacao-externa",
85
+ "stageId": "entrega",
86
+ "scope": "POR_ALVO",
87
+ "evaluationMode": "DETERMINISTICA",
88
+ "requiredEvidence": ["destination.delivery.observed"],
89
+ "evaluatorCapabilities": [],
90
+ "minAttestationsPerEvidence": 1,
91
+ "minDistinctAttesterControlDomains": 1,
92
+ "minApprovals": 1,
93
+ "minDistinctControlDomains": 1,
94
+ "producerDisjoint": true,
95
+ "rejectionIsBinding": true,
96
+ "rubricDigest": "sha256:3333333333333333333333333333333333333333333333333333333333333333"
97
+ }
98
+ ],
99
+ "adapters": [
100
+ {
101
+ "adapterId": "destination.document",
102
+ "version": "1.0.0",
103
+ "capabilities": ["content.target.deliver", "content.target.confirm"],
104
+ "acceptedMediaTypes": ["text/html", "text/markdown"],
105
+ "formatProfiles": ["long-form"],
106
+ "deterministicConstraints": [
107
+ {
108
+ "constraintId": "document-non-empty",
109
+ "kind": "artifact.bytes.min",
110
+ "config": { "minimum": 1 }
111
+ }
112
+ ],
113
+ "requiredMetadata": ["title"],
114
+ "optionalMetadata": [],
115
+ "confirmationPredicates": ["destination.delivery.observed"]
116
+ },
117
+ {
118
+ "adapterId": "destination.audio-feed",
119
+ "version": "1.0.0",
120
+ "capabilities": ["content.target.deliver", "content.target.confirm"],
121
+ "acceptedMediaTypes": ["audio/mpeg", "audio/mp4"],
122
+ "formatProfiles": ["spoken-episode"],
123
+ "deterministicConstraints": [
124
+ {
125
+ "constraintId": "audio-duration-positive",
126
+ "kind": "media.duration.min",
127
+ "config": { "minimum": 1 }
128
+ }
129
+ ],
130
+ "requiredMetadata": ["title", "description"],
131
+ "optionalMetadata": [],
132
+ "confirmationPredicates": ["destination.delivery.observed"]
133
+ }
134
+ ],
135
+ "requiredCompletionGates": ["qa-mestre", "qa-destino", "confirmacao-externa"]
136
+ }