context-motilis 0.0.1__tar.gz

context_motilis-0.0.1/.gitignore

@@ -0,0 +1,28 @@
+# Never committed (§1.2): household data and store files.
+cultures/
+artifacts/
+*.sqlite*
+.env
+.env.*
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+htmlcov/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store

context_motilis-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cetatec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

context_motilis-0.0.1/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.5
+Name: context-motilis
+Version: 0.0.1
+Summary: A local-first runtime for resumable context.
+Project-URL: Homepage, https://github.com/cetatec/context-motilis
+Project-URL: Source, https://github.com/cetatec/context-motilis
+Author: cetatec
+License-Expression: MIT
+License-File: LICENSE
+Keywords: context,local-first,mcp,provenance,runtime
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: mcp==2.2.0
+Requires-Dist: pydantic<3,>=2.12
+Requires-Dist: typer<1,>=0.16
+Description-Content-Type: text/markdown
+
+# context-motilis
+
+A local-first runtime for resumable context.
+
+A **context** is a durable unit — a matter, later an entity or an archive — that
+can be suspended for months and resumed by a person or by any model, with its
+evidence, history, accepted state, commitments in both directions, and dates
+intact. The runtime captures inputs durably before it processes them, keeps time
+and fires reminders without a model, authorizes changes by their consequences,
+records every version with its provenance, and produces a deterministic **brief**
+that answers "where were we?" without rereading history.
+
+The model interprets and proposes; the runtime preserves, schedules, and
+authorizes. A dormant context owns no running process; the shared runtime reacts
+to indexed dates and events on its behalf.
+
+Tools provide capabilities. context-motilis provides continuity.
+
+## Status
+
+Stage 1, tasks 1 through 7 of §10 are merged: the store, contexts, the scheduler,
+capture, the brief, export and import, and the CLI host with `motilis demo`
+replaying the stage-1 script of §9. Twenty-three of the twenty-nine stage-1
+acceptance cases are real tests; the six still pending are all MCP, and land
+with task 8.
+
+What is absent: the MCP host (`motilis serve` as a server), and with it
+elicitation over MCP and `context://inbox`. Under the default fake clock `serve`
+runs a bounded number of passes; staying up is [ADR 0012](docs/adr/0012-serve-waits-through-the-clock.md)
+and task 8.
+
+Two things a new user should know before typing. The CLI is the human's host:
+`note`, `commit`, `remind`, `open`, `ask`, `why`, `due` and `tick` work on a
+clean checkout with no model anywhere. `say` needs a model, this repository
+holds none (§11.1), and in stage 1 free text is interpreted through MCP, where
+the model is the client; on the CLI `say` replays a recorded reading and
+refuses plainly without one. The demo is the way to see the whole loop:
+
+```
+uvx --from git+https://github.com/cetatec/context-motilis motilis demo
+```
+
+The remaining gate is checkpoint 1 (§1.3), run by the owner.
+
+## The brief
+
+[`docs/brief-v7.md`](docs/brief-v7.md) is the controlling specification, committed
+verbatim. Every `§` reference in this repository, in its tests and in its commit
+messages points into it. It is authoritative: where it and any other document in
+this repository disagree, it governs. Revisions supersede one another by number,
+and v7 is the one in force.
+
+[`docs/roadmap.md`](docs/roadmap.md) indexes where the work stands against §7 and
+§10; it decides nothing.
+
+## Install
+
+Before the first release:
+
+```
+uvx --from git+https://github.com/cetatec/context-motilis motilis version
+```
+
+Once released:
+
+```
+uvx --from context-motilis motilis version
+# or
+uv tool install context-motilis && motilis version
+```
+
+The package name and the executable name differ; `--from` is not optional.
+
+## Develop
+
+Python ≥ 3.12 and [uv](https://docs.astral.sh/uv/).
+
+```
+uv sync --group dev
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+uv run pytest
+```
+
+Enable the hygiene hook once per clone, so household data and store files cannot
+be committed:
+
+```
+git config core.hooksPath .githooks
+```
+
+The same check runs in CI, so a bypassed hook still fails the build.
+
+## What is never in this repository
+
+Household data, real names, real documents, `.sqlite` files, `artifacts/` and
+`cultures/`. CI runs with no model, no network and no secrets.
+
+## Layout
+
+```
+src/context_motilis/   the runtime and its hosts
+tests/invariants/      one property test per invariant of §3
+tests/acceptance/      the §8 acceptance suite, by stable name
+docs/brief-v7.md       the controlling specification; every § points here
+docs/adr/              decisions the brief does not settle, and why
+docs/hosts.md          pinned protocol revision, SDK, and tested client builds
+docs/roadmap.md        where the work stands against §7 and §10
+fixtures/              generated fixtures only
+tools/                 repository tooling, not part of the package
+```
+
+## Licence
+
+MIT. See [`LICENSE`](LICENSE), and [ADR 0001](docs/adr/0001-mit-licence.md) for
+why. Reuse is meant to be straightforward, commercial reuse included.
+
+## Two sentences
+
+*Runtime:* A context is a durable boundary that can be suspended and
+independently resumed. It retains evidence and history, may carry commitments
+and deterministic behavior, and exposes a bounded brief to whichever human or
+model attends to it next.
+
+*Development principle:* What exactly must survive this kill? A feature that
+cannot name what survives its kill is not added.

context_motilis-0.0.1/README.md

@@ -0,0 +1,126 @@
+# context-motilis
+
+A local-first runtime for resumable context.
+
+A **context** is a durable unit — a matter, later an entity or an archive — that
+can be suspended for months and resumed by a person or by any model, with its
+evidence, history, accepted state, commitments in both directions, and dates
+intact. The runtime captures inputs durably before it processes them, keeps time
+and fires reminders without a model, authorizes changes by their consequences,
+records every version with its provenance, and produces a deterministic **brief**
+that answers "where were we?" without rereading history.
+
+The model interprets and proposes; the runtime preserves, schedules, and
+authorizes. A dormant context owns no running process; the shared runtime reacts
+to indexed dates and events on its behalf.
+
+Tools provide capabilities. context-motilis provides continuity.
+
+## Status
+
+Stage 1, tasks 1 through 7 of §10 are merged: the store, contexts, the scheduler,
+capture, the brief, export and import, and the CLI host with `motilis demo`
+replaying the stage-1 script of §9. Twenty-three of the twenty-nine stage-1
+acceptance cases are real tests; the six still pending are all MCP, and land
+with task 8.
+
+What is absent: the MCP host (`motilis serve` as a server), and with it
+elicitation over MCP and `context://inbox`. Under the default fake clock `serve`
+runs a bounded number of passes; staying up is [ADR 0012](docs/adr/0012-serve-waits-through-the-clock.md)
+and task 8.
+
+Two things a new user should know before typing. The CLI is the human's host:
+`note`, `commit`, `remind`, `open`, `ask`, `why`, `due` and `tick` work on a
+clean checkout with no model anywhere. `say` needs a model, this repository
+holds none (§11.1), and in stage 1 free text is interpreted through MCP, where
+the model is the client; on the CLI `say` replays a recorded reading and
+refuses plainly without one. The demo is the way to see the whole loop:
+
+```
+uvx --from git+https://github.com/cetatec/context-motilis motilis demo
+```
+
+The remaining gate is checkpoint 1 (§1.3), run by the owner.
+
+## The brief
+
+[`docs/brief-v7.md`](docs/brief-v7.md) is the controlling specification, committed
+verbatim. Every `§` reference in this repository, in its tests and in its commit
+messages points into it. It is authoritative: where it and any other document in
+this repository disagree, it governs. Revisions supersede one another by number,
+and v7 is the one in force.
+
+[`docs/roadmap.md`](docs/roadmap.md) indexes where the work stands against §7 and
+§10; it decides nothing.
+
+## Install
+
+Before the first release:
+
+```
+uvx --from git+https://github.com/cetatec/context-motilis motilis version
+```
+
+Once released:
+
+```
+uvx --from context-motilis motilis version
+# or
+uv tool install context-motilis && motilis version
+```
+
+The package name and the executable name differ; `--from` is not optional.
+
+## Develop
+
+Python ≥ 3.12 and [uv](https://docs.astral.sh/uv/).
+
+```
+uv sync --group dev
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+uv run pytest
+```
+
+Enable the hygiene hook once per clone, so household data and store files cannot
+be committed:
+
+```
+git config core.hooksPath .githooks
+```
+
+The same check runs in CI, so a bypassed hook still fails the build.
+
+## What is never in this repository
+
+Household data, real names, real documents, `.sqlite` files, `artifacts/` and
+`cultures/`. CI runs with no model, no network and no secrets.
+
+## Layout
+
+```
+src/context_motilis/   the runtime and its hosts
+tests/invariants/      one property test per invariant of §3
+tests/acceptance/      the §8 acceptance suite, by stable name
+docs/brief-v7.md       the controlling specification; every § points here
+docs/adr/              decisions the brief does not settle, and why
+docs/hosts.md          pinned protocol revision, SDK, and tested client builds
+docs/roadmap.md        where the work stands against §7 and §10
+fixtures/              generated fixtures only
+tools/                 repository tooling, not part of the package
+```
+
+## Licence
+
+MIT. See [`LICENSE`](LICENSE), and [ADR 0001](docs/adr/0001-mit-licence.md) for
+why. Reuse is meant to be straightforward, commercial reuse included.
+
+## Two sentences
+
+*Runtime:* A context is a durable boundary that can be suspended and
+independently resumed. It retains evidence and history, may carry commitments
+and deterministic behavior, and exposes a bounded brief to whichever human or
+model attends to it next.
+
+*Development principle:* What exactly must survive this kill? A feature that
+cannot name what survives its kill is not added.

context_motilis-0.0.1/docs/adr/0001-mit-licence.md

@@ -0,0 +1,50 @@
+# 0001. The project is licensed MIT
+
+**Status:** accepted
+**Date:** 2026-09-12
+**Question:** [#1](https://github.com/cetatec/context-motilis/issues/1), labelled `question`
+**Decided by:** the project owner, answering that issue
+
+## Context
+
+The brief requires publishing `0.0.x` early, to PyPI by trusted publishing
+(§1.1). It does not name a licence. A licence is not a question an agent may
+settle on the owner's behalf, so `pyproject.toml` carried no `license` field
+and the repository had no `LICENSE` file. The first release was blocked on it,
+and nothing else was.
+
+## Decision
+
+MIT.
+
+## Rationale
+
+In the owner's words:
+
+> Motilis uses MIT to favor straightforward reuse and broad adoption, including
+> commercial reuse. We accept that others may build competing products. Our
+> commercial experiments will focus on additional value, not on charging for
+> permission already granted by the open-source license.
+
+## Consequences
+
+- Anyone may use, modify, redistribute and sell this software, including inside
+  a closed-source product and including in direct competition. This is accepted,
+  not a side effect to be mitigated later by relicensing.
+- No patent grant is made or received. Apache-2.0 would have given one. This was
+  the trade taken in exchange for the simplest possible terms.
+- Contributions arrive under the same terms, so no contributor licence agreement
+  is needed and none should be introduced without a superseding record.
+- Any future commercial offering has to be worth paying for on its own, because
+  the licence already grants permission. Relicensing the existing code away from
+  MIT would not retract what is already granted.
+- `LICENSE` is included in the built distributions, so the terms travel with the
+  package rather than living only in the repository.
+
+## Implementation
+
+`LICENSE` at the repository root; `license = "MIT"` and
+`license-files = ["LICENSE"]` in `pyproject.toml`, as an SPDX expression rather
+than a classifier. The copyright line names `cetatec`, matching the GitHub owner
+and the package author. If a legal entity should hold the copyright instead,
+that is an amendment to this record, not a new decision.

context_motilis-0.0.1/docs/adr/0002-as-of-is-a-position.md

@@ -0,0 +1,47 @@
+# 0002. `as_of` is a position in the committed order
+
+**Status:** accepted
+**Date:** 2026-09-12
+**Question:** [#8](https://github.com/cetatec/context-motilis/issues/8), labelled `question`
+**Decided by:** the project owner, accepting the answer on that issue
+
+## Context
+
+§5.1 makes `(epoch, sequence)` the committed order and says timestamps are data,
+never order. §3 `canonical_record` asks for a `canon/1` state-hash rebuild "at
+`as_of`", and the brief does not say in so many words what `as_of` is made of.
+Two readings were available: a position in that order, or a wall-clock instant.
+
+The reading matters because `as_of` is the boundary a replay stops at and the
+thing two state hashes must share before they can be compared at all.
+
+## Decision
+
+`as_of` is a position in the committed event order, `(epoch, sequence)`. Never a
+time.
+
+## Rationale
+
+A timestamp cutoff does not identify one boundary. Events can share a timestamp,
+and nothing in the brief makes event timestamps monotonic — §5.1 says the
+opposite, that timestamps are data. So "every event at or before time T" can
+name several different sets of events, and a hash taken at one of them is not
+comparable with a hash taken at another. A position names exactly one prefix of
+the record.
+
+It also keeps one rule rather than two. If `as_of` were a time, the store would
+order by `(epoch, sequence)` and cut by timestamp, and the two would disagree the
+first time a clock moved.
+
+## Consequences
+
+- `store.events.Position` is the value `as_of` names, and `hashes.state_hashes`
+  serializes its `epoch` and `sequence` into the overall hash.
+- An export manifest carries two different things: the `as_of` through which the
+  materialization was rebuilt, and the position of the event recording that the
+  export happened. They are not the same number and neither substitutes.
+- State hashes are comparable only at the same `as_of`, which the brief already
+  required and this makes checkable.
+
+No code changed: task 2 implemented this reading, and the decision records why
+it was the only one available rather than a choice that happened to be made.

context_motilis-0.0.1/docs/adr/0003-follow-up-lag-follows-its-definition.md

@@ -0,0 +1,52 @@
+# 0003. `follow_up_lag` follows its definition, not the demo figure
+
+**Status:** accepted
+**Date:** 2026-09-12
+**Question:** [#15](https://github.com/cetatec/context-motilis/issues/15), labelled `question`
+**Decided by:** the project owner, accepting the answer on that issue
+
+## Context
+
+§4.10 defines the first overdue follow-up twice, and the two do not agree.
+
+The rule: "for an open commitment owed to us, at `D + follow_up_lag`, shifted to
+`quiet_hours_end` if inside quiet hours".
+
+The constant: "`follow_up_lag` = next `quiet_hours_end` after D (demo: Sat
+09:00)".
+
+With the default quiet hours — 21:00–08:00 Europe/Paris — the next
+`quiet_hours_end` after a Friday 23:59:59 deadline is Saturday **08:00**, not
+the 09:00 the parenthesis shows.
+
+## Decision
+
+The definition governs. `follow_up_lag(D) = quiet_hours_end(D)`, and the demo's
+"Sat 09:00" is a documentation error that should read 08:00.
+
+The trailing "shifted to `quiet_hours_end` if inside quiet hours" is already
+what the lag *is*, so it is not applied a second time. Repeats are different:
+they are `previous + follow_up_cooldown` and only then shifted, because a
+cooldown is not defined in terms of quiet hours.
+
+## Rationale
+
+A definition and an example that disagree are not two requirements; one of them
+is wrong. The definition is the one written as a rule, it composes with the
+quiet-hours constant the brief also states, and it is the one the algorithm can
+be derived from. The parenthesis is an illustration, and an illustration that
+contradicts its own defaults illustrates nothing.
+
+Applying the shift twice would be worse than redundant. At exactly 08:00 the
+boundary rule says the moment is not inside quiet hours, so a second application
+is a no-op today — but a later change to that boundary would silently start
+advancing every first follow-up by a day.
+
+## Consequences
+
+- A Friday 23:59:59 Paris deadline produces its first follow-up at Saturday
+  08:00 Paris, `2026-09-12T06:00:00Z`.
+- `ACC-clock-cases` asserts that, and `scheduler/rules.follow_up_lag_surface` is
+  one line because of it.
+- The brief's own parenthesis still says 09:00. Correcting the specification is
+  the owner's to make; this record is why the implementation does not match it.

context_motilis-0.0.1/docs/adr/0004-scheduling-inputs-are-read-when-the-occurrence-is-created.md

@@ -0,0 +1,56 @@
+# 0004. Scheduling inputs are read when the occurrence is created
+
+**Status:** accepted
+**Date:** 2026-09-12
+**Question:** [#16](https://github.com/cetatec/context-motilis/issues/16), labelled `question`
+**Decided by:** the project owner, accepting the answer on that issue
+
+## Context
+
+§4.10 computes a pre-deadline reminder from the deadline `D` and the act `A`,
+and `A` comes from the context's `next`. So stating a `next` after a date, or
+changing its act later, changes what §4.10 would compute for that date.
+
+§3 `occurrence` says the opposite thing about what may move: at most one logical
+occurrence per effect key, "with its original scheduled time preserved". The key
+carries the node and the deadline, not the act.
+
+## Decision
+
+The effective `due`, `next.act` and confirmed `next.remind_at` are read when the
+logical occurrence is **first scheduled**. A later change to any of them does
+not move an occurrence that already exists.
+
+## Rationale
+
+§3's sentence is the more specific of the two and the one written as an
+invariant. §4.10 says how a surface time is computed; it does not say the
+computation is repeated against an occurrence that has already been placed.
+
+Putting the act in the effect key was the alternative and is worse in a way that
+is easy to miss: an act edited after the reminder has already fired would mint a
+second key, and for a deadline in the past that second occurrence surfaces
+immediately as a catch-up. A metadata correction would ring a bell.
+
+## Consequences
+
+- `desired` recomputes from current state and so reports a time the table does
+  not hold, for any occurrence whose inputs changed after it was scheduled. The
+  disagreement is real and is recorded by
+  `test_an_act_stated_after_a_date_does_not_move_its_reminder`.
+- **There is no way to move a scheduled reminder.** The original issue text
+  offered a confirmed `remind_at` as the owner's escape hatch. That was wrong:
+  the key does not carry `remind_at` either, so a later one is the same spent
+  key and reconciliation skips it. Pinned by
+  `test_a_later_confirmed_remind_at_does_not_move_it_either`. Moving an
+  occurrence that exists would need an explicit reschedule, which the brief does
+  not describe and which is not in stage 1.
+- Urgency is the one input that reaches an occurrence after the fact, and it
+  does so by minting a different key rather than by re-timing one. See
+  [0005](0005-urgent-is-a-flag-on-the-two-occurrence-sources.md).
+
+A follow-up worth taking when the model is next touched: `desired` could report
+the stored time for an occurrence that exists and the computed time only for one
+that does not, so it stops claiming a time reconciliation will never apply. That
+is behaviour-neutral and was deliberately left out of the change that answered
+this question, because it presumes the answer.

context_motilis-0.0.1/docs/adr/0005-urgent-is-a-flag-on-the-two-occurrence-sources.md

@@ -0,0 +1,74 @@
+# 0005. `urgent` is a flag on `commitment` and `date`
+
+**Status:** accepted
+**Date:** 2026-09-12
+**Question:** [#18](https://github.com/cetatec/context-motilis/issues/18), labelled `question`
+**Decided by:** the project owner, accepting the answer on that issue
+
+## Context
+
+§4.10 ends its precedence paragraph with one clause:
+
+> `urgent` sets `surface = min(surface, now)`.
+
+That is the only occurrence of the word in the brief. No §4.4 kind carries the
+flag, no §6.1 operation sets it, no §5 table stores it, and §4.8's authority
+table says nothing about who may declare something urgent. The rule could not be
+implemented without first deciding where urgency lives, which §11.4 makes an
+approval twice over: a field on a kind §4.4 enumerates, and a change to §4.10's
+precedence.
+
+## Decision
+
+A boolean `urgent`, defaulting to `false`, on `commitment` and `date` — the two
+kinds §4.10 names as occurrence sources. Effective only from an **accepted**
+version. It clamps the **pre-deadline reminder** only, at the reconciliation
+instant, and it is part of that occurrence's effect key.
+
+## Rationale
+
+**On the node, not the occurrence.** Urgency is a property of the thing, not of
+the reminder about it. On an occurrence it would be unreachable from a mutation
+set and would not survive the node being superseded.
+
+**Not on `next`.** A `next` raises no occurrence of its own — §4.10 says "for a
+commitment or date with due D and act A" — so an `urgent` there would have
+nothing to act on.
+
+**Accepted only**, the rule `remind_at` already follows (§4.5). A model that
+could mark its own extraction urgent could make the runtime interrupt the owner
+on the strength of an untrusted document, which is the shape §4.8 exists to
+prevent. A fallback-derived node is not schedulable at all, so it never reaches
+the question.
+
+**Pre-deadline only.** An overdue follow-up exists *because* the deadline
+passed, so "surface it sooner" has nothing to mean for it, and an urgent overdue
+commitment would otherwise fire twice at once. §4.10 fixes both expiry times to
+the expiry itself, and a thing does not lapse sooner for being urgent.
+
+**In the effect key**, which is the part that took implementing to see.
+Acceptance lands *after* the mutation carrying it — `apply_set` reconciles, then
+`confirm` accepts and reconciles again — so by the moment urgency is effective
+the ordinary reminder has already been scheduled and its key is spent. Without
+urgency in the key the rule could never fire on the case it exists for: a thing
+created urgent. With it, the base key drops out of `desired` as the urgent one
+appears, so reconciliation cancels it in the same pass and one occurrence stands.
+§3 is satisfied per key, each keeping its own original time.
+
+**Only the time depends on the instant, never the key.** `tick.stale_reason`
+asks whether an occurrence's key is still in `desired`, and asks without a
+reconciliation instant. When urgency lived in both, every urgent occurrence was
+cancelled as "no longer implied" moments before delivery — the tick destroying
+the thing urgency is for. The key is a fact about state; `now` only clamps.
+
+## Consequences
+
+- Something created urgent surfaces at the instant its acceptance is
+  reconciled, and is delivered by the next tick like anything else.
+- `min`, not "set to now": a reminder already due keeps its earlier time.
+- Marking an existing commitment urgent cancels its ordinary reminder and
+  schedules an urgent one; the cancelled row still records when it was going to
+  surface.
+- **Urgency cannot be taken back.** Un-marking it finds the base key spent and
+  schedules nothing. That is the right way round — the owner has already been
+  told — but it is a one-way door and is stated here rather than discovered.