@ifsoul/core 0.3.0 → 0.4.0

package/specs/memory/README.md

@@ -1,80 +0,0 @@
-# Memory contracts
-
-Historical v0.1 contract. See [v0.2](../v0.2/README.md) for the current design;
-the v0.1 JSON examples remain unchanged for regression checks.
-
-A Memory Event records what a source supplied to an observer, with provenance.
-It is not a universally true fact. A Derived Memory is replaceable interpretation
-or indexing data built from raw events; it never replaces them automatically.
-Neither format grants permission or acts as a trusted instruction.
-
-| Document       | Required fields beyond `schemaVersion`, `kind`                                                                                        |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| Memory Event   | `eventId`, `characterId`, `worldId`, `sessionId`, `source`, `observerId`, `recordedAt`, `worldTime`, `scope`, `payload`, `provenance` |
-| Derived Memory | `memoryId`, `characterId`, `createdAt`, `scope`, `sourceEventIds`, `derivation`, `payload`                                            |
-
-A source has `sourceId`, `kind` (`world-adapter`, `runtime`, `user`, or `import`),
-and a nonnegative `sequence`. Sequence is ordered only within that source's
-world/session stream; duplicates or regressions require explicit reconciliation.
-`recordedAt` is wall-clock recording time; `worldTime` is the separately named
-world timeline and tick. Neither defines global order across sources. Importers
-MUST preserve original source/provenance rather than manufacture fresh historical
-truth or treat equal ticks from different timelines as comparable.
-
-An event payload has an opaque `type` and open object `data`; interpreting that
-data requires a known payload contract. `provenance.eventIds` and
-`provenance.worldEventIds` are unique ID arrays, empty when no source references
-exist. A future consumer checks identity, accessible references, source-local
-sequence ordering, and consistency with the character/world mapping. Optional
-`confidence` lies in `[0,1]`; it is a source-supplied score, not a calibrated
-probability, consensus, or permission.
-
-## Access and export scope
-
-Every event, derived record, world event, and observation item has a `scope`:
-`audience`, `subjectIds`, and `export`.
-
-- `private` requires exactly one subject ID: the intended subject.
-- `participants` requires at least one explicit subject ID and exposes data only
-  to those subjects under trusted policy.
-- `public` requires an empty subject list. It describes world-audience visibility,
-  not permission to publish player data on the Internet.
-
-These list/cardinality relationships are semantic checks in this baseline.
-Subject IDs use the record's world/session context; a derived record resolves
-subjects through its source events. If source contexts differ, trusted identity
-mapping and a scope no broader than every source's access are required; without
-that mapping the derivation MUST be rejected. A string copied from an imported
-record is never sufficient proof of identity.
-
-`export` is `allowed`, `consent-required`, or `forbidden`. Access and export are
-separate decisions: visibility does not imply export consent. `allowed` remains
-subject to actual authorization; `consent-required` needs verifiable consent;
-`forbidden` is excluded. Filtering MUST report losses without exposing withheld
-payloads. Scope enforcement and consent verification are not schema checks.
-
-## Derived records
-
-`sourceEventIds` is a nonempty unique array. `derivation` requires `algorithmId`
-and `algorithmVersion`, plus `modelId` when a model contributed. Payloads are
-explicit variants:
-
-| `payload.type` | Fields                                                      |
-| -------------- | ----------------------------------------------------------- |
-| `fact`         | `text`                                                      |
-| `relationship` | `subjectId`, `relation`, `objectId`, optional `description` |
-| `summary`      | `text`                                                      |
-| `embedding`    | Nonempty numeric `vector`                                   |
-
-A fact is a derived claim; a relationship is not consent. Embedding model,
-preprocessing, and dimensional compatibility MUST be recorded by the derivation
-identity/version and checked before use. Derived records can be regenerated
-when algorithms change. Source data remains available until explicit authorized
-deletion; summaries do not justify silent source deletion. Deleting or losing
-access to source events requires deleting or recomputing dependent derived
-records and indexes. Retention of older backups needs a separate policy.
-
-The [event](examples/memory-event.json) refers to the synthetic watering world
-event; the [summary](examples/derived-memory.json) derives from that event.
-Storage, querying, deletion propagation, cross-world mapping, and derivation
-execution are not implemented.

package/specs/memory/examples/derived-memory.json

@@ -1,21 +0,0 @@
-{
-  "schemaVersion": "draft-0.1.0",
-  "kind": "derived-memory",
-  "memoryId": "summary-1",
-  "characterId": "character-mira",
-  "createdAt": "2026-01-01T12:00:00Z",
-  "scope": {
-    "audience": "private",
-    "subjectIds": ["actor-mira"],
-    "export": "allowed"
-  },
-  "sourceEventIds": ["memory-event-1"],
-  "derivation": {
-    "algorithmId": "synthetic-summary",
-    "algorithmVersion": "1"
-  },
-  "payload": {
-    "type": "summary",
-    "text": "Mira observed that the watering action completed."
-  }
-}

package/specs/memory/examples/memory-event.json

@@ -1,35 +0,0 @@
-{
-  "schemaVersion": "draft-0.1.0",
-  "kind": "memory-event",
-  "eventId": "memory-event-1",
-  "characterId": "character-mira",
-  "worldId": "garden",
-  "sessionId": "session-1",
-  "source": {
-    "sourceId": "garden-recorder",
-    "kind": "runtime",
-    "sequence": 1
-  },
-  "observerId": "actor-mira",
-  "recordedAt": "2026-01-01T12:00:00Z",
-  "worldTime": {
-    "timelineId": "garden-day-1",
-    "tick": 20
-  },
-  "scope": {
-    "audience": "private",
-    "subjectIds": ["actor-mira"],
-    "export": "allowed"
-  },
-  "payload": {
-    "type": "observed-action-result",
-    "data": {
-      "actionId": "action-water-1",
-      "status": "success"
-    }
-  },
-  "provenance": {
-    "eventIds": [],
-    "worldEventIds": ["world-event-water-1"]
-  }
-}

package/specs/model-provider/README.md

@@ -1,85 +0,0 @@
-# ModelProvider contract
-
-This provider boundary remains independently versioned at `draft-0.1.0` while
-the [character/environment design](../v0.2/README.md) advances to v0.2. A provider
-performs inference; an external AgentController is a separately planned runtime
-strategy, not a synonym for a provider or permission to execute game commands.
-
-ModelProvider is a planned boundary for structured model input/output,
-capability declaration, usage, cancellation/deadlines, and safe errors. It is
-independent of a vendor, SDK, game, cloud account, and transport. This bootstrap
-contains no model client or inference implementation and does not require a key.
-
-The [model-provider schema](../../packages/protocol/schemas/model-provider.schema.json)
-is a tagged union. Every variant requires `schemaVersion` and `kind`:
-
-| `kind`                  | Required additional fields                                                                   |
-| ----------------------- | -------------------------------------------------------------------------------------------- |
-| `provider-capabilities` | `providerId`, `modelId`, `toolCalling`, `structuredOutput`, `cancellation`, `usage`          |
-| `model-request`         | `requestId`, `providerId`, `modelId`, `messages`, `toolChoice`, `outputFormat`, `deadlineAt` |
-| `model-response`        | `requestId`, `providerId`, `modelId`, `recordedAt`, `status`, `output`, `finishReason`       |
-| `model-error`           | `requestId`, `providerId`, `modelId`, `recordedAt`, `error`                                  |
-
-Capabilities apply to the exact `providerId` + `modelId`. `toolCalling: false`
-requires requests to omit tools or use an empty array with `toolChoice: "none"`.
-`structuredOutput: false` requires `outputFormat: "text"`. Unsupported features
-MUST be rejected explicitly, never silently removed or emulated as a claimed
-native guarantee. `usage` indicates whether usage can be reported; omission
-means unknown, never zero. Local rules strategies do not need to pretend to be
-model providers.
-
-Requests contain a nonempty `messages` array of `{ role, content }` where role is
-`system`, `user`, `assistant`, or `tool`. Optional assistant `toolCalls` contain
-`toolCallId`, `name`, and object `arguments`; tool-result messages reference a
-`toolCallId`. Tool calls belong only to assistant messages, tool results require
-a prior matching call, and non-tool messages MUST omit `toolCallId`. These are
-semantic checks, not enforced by the enclosing schema. Context selection and
-trust placement are application responsibilities; untrusted memory/tool text
-MUST NOT become trusted system instructions.
-
-Optional tool definitions contain `name`, `description`, and `argumentsSchema`.
-Names and call IDs MUST be unique in their respective request/response context.
-Arguments schemas require separate safe meta-validation and argument validation.
-`toolChoice` is `none`, `auto`, or `required`; `required` needs at least one tool.
-`outputFormat` is `text` or `json-object`; for the latter, a consumer MUST parse
-and verify `output.text` as a JSON object. It does not imply a particular domain
-schema. Optional `maxOutputTokens` requests a provider-supported output bound;
-there is no context-window or billing guarantee. Unsupported limits are rejected.
-
-`deadlineAt` is UTC scheduling time. Optional `cancellationId` correlates a
-future transport's cancellation signal; the schema does not implement the signal
-or define a wire message. `cancellation` is explicitly `unsupported` or
-`best-effort`. Best effort can stop waiting/generation where supported but cannot
-promise rollback, no usage, no billing, or that an upstream request never ran.
-Unsupported cancellation MUST be reported by capabilities and checked before use.
-
-A response's `output` contains `text` and `toolCalls` (possibly empty). Status is
-`completed`, `incomplete`, or `cancelled`. Future consumers MUST enforce these
-semantic combinations: completed uses finish reason `stop` or `tool-calls`;
-incomplete uses `length`; cancelled uses `cancelled`. `tool-calls` requires
-nonempty calls supported by the selected tools; `stop` has no pending tool calls.
-Partial/cancelled output MUST NOT trigger execution automatically. A model tool
-call is a proposal; it must become a separately validated, authorized world
-Action before execution.
-
-Responses and errors correlate `requestId`, `providerId`, and `modelId` to the
-request. Usage optionally contains nonnegative `inputTokens`, `outputTokens`,
-and `estimated`; estimates MUST stay labelled and omitted counts MUST NOT be
-fabricated. No currency, pricing, or normalized cost contract is defined. Usage
-may be present on failure or cancellation.
-
-Errors use `code`, safe `message`, `retry`, and optional `retryAfterMs`. Examples
-of codes are `unsupported-feature`, `invalid-request`, `rate-limited`,
-`unavailable`, `deadline-exceeded`, and `cancelled`; codes are extensible opaque
-IDs, so callers handle unknown codes conservatively. Never include credentials,
-raw private prompts, or upstream secrets in errors. A retry hint is not an
-idempotency guarantee: a timed-out provider request may have consumed usage and
-a repeated request may generate different output or another charge. Preserve
-request provenance and apply local budgets before a retry. Rules decisions can
-be reproducible; replay of recorded output reproduces that fixture; live model
-responses are not promised deterministic across models or versions.
-
-Positive synthetic examples: [capabilities](examples/capabilities.json),
-[request](examples/request.json), [response](examples/response.json),
-[error](examples/error.json). Response and error are alternative outcomes, not
-two mandatory messages. No hidden model reasoning is required or stored.

package/specs/model-provider/examples/capabilities.json

@@ -1,10 +0,0 @@
-{
-  "schemaVersion": "draft-0.1.0",
-  "kind": "provider-capabilities",
-  "providerId": "synthetic-provider",
-  "modelId": "fixture-model",
-  "toolCalling": false,
-  "structuredOutput": false,
-  "cancellation": "unsupported",
-  "usage": true
-}

package/specs/model-provider/examples/error.json

@@ -1,18 +0,0 @@
-{
-  "schemaVersion": "draft-0.1.0",
-  "kind": "model-error",
-  "requestId": "request-1",
-  "providerId": "synthetic-provider",
-  "modelId": "fixture-model",
-  "recordedAt": "2026-01-01T12:00:00Z",
-  "error": {
-    "code": "deadline-exceeded",
-    "message": "No complete response was received before the deadline.",
-    "retry": "same-request"
-  },
-  "usage": {
-    "inputTokens": 13,
-    "outputTokens": 0,
-    "estimated": true
-  }
-}

package/specs/model-provider/examples/request.json

@@ -1,17 +0,0 @@
-{
-  "schemaVersion": "draft-0.1.0",
-  "kind": "model-request",
-  "requestId": "request-1",
-  "providerId": "synthetic-provider",
-  "modelId": "fixture-model",
-  "messages": [
-    {
-      "role": "user",
-      "content": "Describe the visible garden plant in one sentence."
-    }
-  ],
-  "toolChoice": "none",
-  "outputFormat": "text",
-  "deadlineAt": "2026-01-01T12:00:05Z",
-  "maxOutputTokens": 32
-}

package/specs/model-provider/examples/response.json

@@ -1,19 +0,0 @@
-{
-  "schemaVersion": "draft-0.1.0",
-  "kind": "model-response",
-  "requestId": "request-1",
-  "providerId": "synthetic-provider",
-  "modelId": "fixture-model",
-  "recordedAt": "2026-01-01T12:00:00Z",
-  "status": "completed",
-  "output": {
-    "text": "A small plant stands beside the path.",
-    "toolCalls": []
-  },
-  "finishReason": "stop",
-  "usage": {
-    "inputTokens": 13,
-    "outputTokens": 10,
-    "estimated": true
-  }
-}