@pathmx/completion 0.5.0

package/LICENSE.md

@@ -0,0 +1,172 @@
+# PathMX Proprietary Beta License
+
+Version 0.1 — July 21, 2026
+
+Copyright © 2026 DUO Interactive, LLC.
+All rights reserved.
+
+This license governs the first-party PathMX software distributed in the npm
+package `@pathmx/core`, including its command-line interface, bundled
+library surfaces, runtime and Player components, and accompanying
+documentation (the “Software”). DUO Interactive, LLC is the “Licensor.” This
+license does not cover the private PathMX source-code repository or separately
+identified third-party materials.
+
+“Project” means Paths, Sources, responses, data, and other content authored or
+processed with the Software.
+
+“Application” means software or a service created by you in which the Software
+supports product-specific functionality but is not itself offered as a
+general-purpose PathMX product.
+
+“Redistributable Components” means runtime, Player, or library portions of the
+Software incorporated into a Project, Application, or generated output through
+ordinary use of the Software or ordinary compilation and bundling tools.
+
+“Authorized Users” means your employees and individual contractors who use the
+Software on your behalf, and your hosting, continuous-integration, and other
+service providers that possess or run necessary copies solely to provide
+services to you.
+
+## 1. Agreement
+
+By installing, accessing, or using the Software, you agree to this license. If
+you use the Software on behalf of an organization, you represent that you have
+authority to accept this license for that organization. If you do not agree,
+do not install or use the Software.
+
+## 2. License grant
+
+Subject to this license, the Licensor grants you a non-exclusive, worldwide,
+royalty-free, non-transferable, and non-sublicensable license, perpetual for
+the version of the Software to which it applies unless terminated under
+Section 10, to:
+
+- install, execute, and use the Software for personal, educational,
+  internal-business, or commercial purposes;
+- use the Software to author, integrate, build, test, serve, play, host, and
+  operate Projects and Applications;
+- import, compile, bundle, configure, and integrate the Software through its
+  documented library and command-line interfaces;
+- create and distribute independent Projects, Applications, plugins, and
+  integrations that use those interfaces without modifying the Software
+  itself; and
+- make copies reasonably necessary for local development, testing, continuous
+  integration, backup, and hosted production environments.
+
+Your Authorized Users may exercise those rights solely on your behalf. You are
+responsible for their compliance with this license.
+
+You may reproduce and distribute Redistributable Components only as
+incorporated into your Project, Application, or generated output, and only when
+you preserve applicable license and proprietary notices. You may host and
+commercially provide access to that Project, Application, or output. You may
+not distribute Redistributable Components as a standalone package or as a
+general-purpose substitute for the Software.
+
+Each lawful recipient of a Redistributable Component may execute and use that
+component, display its output, and make technically necessary transitory copies
+solely as incorporated into the Project, Application, or output in which they
+received it. This limited recipient permission does not include a right to
+extract, modify, or redistribute the component separately.
+
+## 3. Restrictions
+
+Except where applicable law does not allow the restriction, you may not:
+
+- modify, adapt, translate, or create derivative works of the Software, except
+  for the compilation, bundling, configuration, and integration expressly
+  permitted in Section 2;
+- redistribute, sublicense, sell, lease, or otherwise provide the Software to
+  another person as a standalone package, product, or service except to an
+  Authorized User or as a Redistributable Component under Section 2;
+- resell, rebrand, or provide the Software as a hosted or managed service that
+  gives third parties general-purpose access to substantial PathMX authoring,
+  building, serving, Player-administration, or library functionality for their
+  own unrelated projects;
+- reverse engineer, decompile, disassemble, or otherwise attempt to derive the
+  source code of the Software; or
+- remove or alter copyright, license, trademark, or other proprietary notices.
+
+For clarity, the managed-service restriction does not prohibit a hosted
+Project or Application in which PathMX supports the licensee's own
+product-specific experience and is not itself the general-purpose product
+offered to customers.
+
+## 4. Your content
+
+As between you and the Licensor, you retain ownership of the Paths, Sources,
+responses, data, independent application code, and other content that you
+author or provide while using the Software. You are responsible for that
+content and for having the rights needed to use it.
+
+Generated output may contain Redistributable Components or third-party
+materials. Your ownership of your content does not change the ownership or
+license terms of those components and materials.
+
+## 5. Ownership and trademarks
+
+The Software is licensed, not sold. The Licensor and its suppliers retain all
+rights in the Software not expressly granted by this license. This license
+does not grant permission to use the PathMX name, logos, or other marks except
+as reasonably necessary to identify the Software accurately.
+
+## 6. Beta status and changes
+
+The Software is a proprietary beta release. Its APIs, behavior, file formats,
+and features may change or be removed without notice. The Licensor has no
+obligation to provide support, maintenance, updates, continued availability,
+or backward compatibility. A later version may be offered under different
+license terms, including an open-source license. Different terms for a later
+version do not change the license previously granted for an earlier version.
+
+## 7. Third-party materials
+
+The Software and Redistributable Components may include or depend on
+third-party materials governed by their own license terms. Those terms control
+for the applicable third-party materials. You must preserve third-party notices
+when the applicable third-party terms require it.
+
+## 8. Disclaimer of warranties
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED “AS IS” AND
+“AS AVAILABLE,” WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EXPRESS,
+IMPLIED, OR STATUTORY, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE, TITLE, NON-INFRINGEMENT, OR THAT THE SOFTWARE WILL BE
+SECURE, ERROR-FREE, OR UNINTERRUPTED.
+
+## 9. Limitation of liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE LICENSOR AND ITS CONTRIBUTORS,
+SUPPLIERS, AND AFFILIATES WILL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
+SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES, OR FOR LOSS OF DATA,
+PROFITS, REVENUE, GOODWILL, OR BUSINESS OPPORTUNITY, ARISING FROM OR RELATED TO
+THE SOFTWARE OR THIS LICENSE, EVEN IF ADVISED OF THE POSSIBILITY OF THOSE
+DAMAGES.
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THEIR TOTAL LIABILITY FOR ALL CLAIMS
+ARISING FROM OR RELATED TO THE SOFTWARE OR THIS LICENSE WILL NOT EXCEED THE
+GREATER OF THE AMOUNT YOU PAID FOR THE SOFTWARE DURING THE TWELVE MONTHS BEFORE
+THE EVENT GIVING RISE TO THE CLAIM OR US$100.
+
+## 10. Termination
+
+This license terminates if you materially breach it and do not cure the breach
+within thirty days after receiving written notice from the Licensor. On
+termination, you and your Authorized Users must stop using and delete your
+copies of the Software. Sections 4, 5, 8, 9, 10, and 11 survive termination.
+Termination does not withdraw the limited permission already granted by
+Section 2 to lawful recipients of Redistributable Components distributed
+before termination.
+
+## 11. General
+
+If a provision of this license is unenforceable, it will be modified only to
+the minimum extent necessary to make it enforceable, and the remaining
+provisions will continue in effect. Failure to enforce a provision is not a
+waiver. You may not assign or transfer this license without the Licensor's
+written consent. The Licensor may assign this license together with ownership
+of the Software to a successor owner. This license binds and benefits the
+permitted successors and assigns of you and the Licensor. This license is the
+entire agreement concerning the Software unless you and the Licensor have
+signed a separate agreement that expressly replaces it.

package/README.md

@@ -0,0 +1,171 @@
+# `@pathmx/completion`
+
+The opt-in, domain-neutral Completion primitive for PathMX. It owns stable
+Source-local leaf references, Actor-owned outcomes, flat summaries, State
+persistence, authored manual targets, and the canonical set/unset Action. It
+does not own Path trees, forms, or domain rollups.
+
+```ts
+import { createCompletionPlugin } from "@pathmx/completion"
+
+const completion = createCompletionPlugin()
+
+export const plugins = [completion.plugin]
+
+completion.reader.read(actor.id, {
+  source: "/lessons/setup.page",
+  key: "task/install",
+})
+```
+
+## Authored targets
+
+A Source or authored Block can declare a manual target with the owned
+`completion` schema prop. Source targets use `source/self`; Block targets use
+their required stable authored id:
+
+```md
+---
+completion:
+  target: true
+  label: Finish this lesson
+---
+
+# Lesson
+
+---
+
+<!--
+id: practice
+completion:
+  target: true
+  label: Finish the practice
+  optional: true
+-->
+```
+
+A trailing task mark produces a stable `task/<id>` target without obscuring
+the human label:
+
+```md
+- [ ] Install dependencies {#install}
+- [ ] Explore the bonus {#bonus .optional}
+```
+
+`completionTargets(source)` projects the same frozen target model from a
+canonical `Source` or viewer-safe `SourceView`. The Completion Action is
+available only when the current Source has valid configured targets; it binds
+the Source id and validates the submitted key and optionality.
+
+Domains using Completion-owned manual facts can contribute only their stable
+keys and optionality:
+
+```ts
+const completion = createCompletionPlugin({
+  contributors: [
+    (source) =>
+      source.type === "project"
+        ? [{ key: "project/launch", optional: false }]
+        : [],
+  ],
+})
+```
+
+The domain continues to own labels, structure, and rollups. Derived evidence
+such as a valid Input submission remains owned by its provider and uses a
+separate read contract rather than writing a duplicate manual fact:
+
+```ts
+import { createCompletionPlugin } from "@pathmx/completion"
+import { createInputPlugin } from "@pathmx/core/plugins"
+
+const input = createInputPlugin()
+const completion = createCompletionPlugin({
+  evidence: [input.completion],
+})
+
+export const plugins = [input.plugin, completion.plugin]
+```
+
+Input completion is declared on one stable authored Block, making the form or
+question container—not each field—the semantic leaf:
+
+```md
+<!--
+id: reflection
+input-response:
+  completion: true
+-->
+
+<x-input-text name="response" label="Reflection" required />
+<x-input-submit label="Save response" />
+```
+
+This declares `input/reflection`. It becomes complete only when that Actor has
+a submitted Input State whose values still validate against the current
+authored fields. The derived target never exposes `completion:set` and never
+writes Completion State. Input currently owns one aggregate State per Source,
+so a Source may declare one Input completion Block.
+
+`pmx lint` reports malformed props, unstable Block targets, checked or empty
+marked tasks, invalid and duplicate keys, stale facts, manual/derived
+collisions, and invalid skips for the currently configured contributors and
+evidence providers. Input additionally reports invalid completion containers,
+bound State references, and stored values.
+
+State is grouped by originating Source and stores only terminal leaf outcomes:
+
+```yaml
+---
+type: state
+plugin: completion
+for: /lessons/setup.page
+items:
+  task/install:
+    outcome: complete
+    occurred_at: 2026-08-22T12:00:00.000Z
+  task/bonus:
+    outcome: skipped
+    occurred_at: 2026-08-22T12:05:00.000Z
+---
+```
+
+`occurred_at` is the occurrence time of the current terminal fact. Repeating
+the same outcome preserves it; clearing and completing again records a new
+time. `pending` is represented by the absence of an item. Provider evidence is
+read through the composed Completion reader; domain rollups remain with their
+owning plugins.
+
+## React apps
+
+React remains an optional subpath:
+
+```tsx
+import {
+  CompletionProvider,
+  useCompletion,
+  useCompletionAction,
+} from "@pathmx/completion/react"
+
+function Task() {
+  const fact = useCompletion("task/install")
+  const completion = useCompletionAction("task/install")
+  return (
+    <button
+      disabled={completion.pending}
+      onClick={() => completion.set(fact ? "pending" : "complete")}
+    >
+      {fact ? "Completed" : "Mark complete"}
+    </button>
+  )
+}
+
+;<CompletionProvider initial={serverProjectedFacts}>
+  <Task />
+</CompletionProvider>
+```
+
+The App Component server renderer supplies `serverProjectedFacts` for the
+current viewer. The browser receives no Completion reader or repository
+access. See `labs/assessment/plugins/class-assessment` for a complete App
+Component using the same provider with derived submission completion.

package/contributors.ts

@@ -0,0 +1,145 @@
+import type { Source } from "@pathmx/core"
+import {
+  COMPLETION_KEY,
+  type CompletionFact,
+  type CompletionRef,
+} from "./model.ts"
+import { completionTargets, type CompletionTarget } from "./targets.ts"
+
+export type CompletionContributor = (
+  source: Source,
+) => readonly Readonly<{ key: string; optional?: boolean }>[]
+
+export type CompletionEvidence = Readonly<{
+  declarations: CompletionContributor
+  read(
+    actorId: string,
+    ref: CompletionRef,
+  ): Readonly<{ fact?: CompletionFact }> | undefined
+}>
+
+type CompletionDeclaration = Readonly<{
+  key: string
+  optional: boolean
+}>
+
+function declaration(
+  source: Source,
+  value: Readonly<{ key: string; optional?: boolean }>,
+): { declaration?: CompletionDeclaration; issue?: string } {
+  if (
+    typeof value.key !== "string" ||
+    value.key.length > 256 ||
+    !COMPLETION_KEY.test(value.key)
+  ) {
+    return {
+      issue: `Invalid contributed Completion key ${String(value.key)} on ${source.id}.`,
+    }
+  }
+  if (value.optional !== undefined && typeof value.optional !== "boolean") {
+    return {
+      issue: `Completion target ${value.key} on ${source.id} has invalid optional data.`,
+    }
+  }
+  return {
+    declaration: Object.freeze({
+      key: value.key,
+      optional: value.optional === true,
+    }),
+  }
+}
+
+function inspectDeclarations(
+  source: Source,
+  values: readonly Readonly<{ key: string; optional?: boolean }>[],
+  duplicateLabel: string,
+) {
+  const inspected = values.map((value) => declaration(source, value))
+  const issues = inspected.flatMap(({ issue }) => (issue ? [issue] : []))
+  const valid = inspected.flatMap(({ declaration }) =>
+    declaration ? [declaration] : [],
+  )
+  const counts = new Map<string, number>()
+  for (const target of valid) {
+    counts.set(target.key, (counts.get(target.key) ?? 0) + 1)
+  }
+  for (const [key, count] of counts) {
+    if (count > 1) {
+      issues.push(
+        `Duplicate ${duplicateLabel} Completion target ${key} on ${source.id}.`,
+      )
+    }
+  }
+  return Object.freeze({
+    declarations: Object.freeze(
+      valid.filter((target) => counts.get(target.key) === 1),
+    ),
+    valid: Object.freeze(valid),
+    issues: Object.freeze(issues),
+  })
+}
+
+export function inspectCompletionDeclarations(
+  source: Source,
+  contributors: readonly CompletionContributor[],
+  contentTargets: readonly CompletionTarget[] = completionTargets(source),
+) {
+  return inspectDeclarations(
+    source,
+    [
+      ...contentTargets.map(({ ref, optional }) => ({
+        key: ref.key,
+        optional,
+      })),
+      ...contributors.flatMap((contribute) => contribute(source)),
+    ],
+    "contributed",
+  )
+}
+
+export function inspectConfiguredCompletionDeclarations(
+  source: Source,
+  contributors: readonly CompletionContributor[],
+  evidence: readonly CompletionEvidence[],
+  contentTargets: readonly CompletionTarget[] = completionTargets(source),
+) {
+  const manual = inspectCompletionDeclarations(
+    source,
+    contributors,
+    contentTargets,
+  )
+  const derived = inspectDeclarations(
+    source,
+    evidence.flatMap((provider) => provider.declarations(source)),
+    "derived",
+  )
+  const manualKeys = new Set(manual.valid.map(({ key }) => key))
+  const derivedKeys = new Set(derived.valid.map(({ key }) => key))
+  const collisions = [...manualKeys].filter((key) => derivedKeys.has(key))
+  return Object.freeze({
+    manual: Object.freeze(
+      manual.declarations.filter(({ key }) => !derivedKeys.has(key)),
+    ),
+    derived: Object.freeze(
+      derived.declarations.filter(({ key }) => !manualKeys.has(key)),
+    ),
+    issues: Object.freeze([
+      ...manual.issues,
+      ...derived.issues,
+      ...collisions.map(
+        (key) =>
+          `Completion target ${key} on ${source.id} is both manual and derived.`,
+      ),
+    ]),
+  })
+}
+
+/** Combine built-in content declarations with configured domain contributors. */
+export function completionDeclarations(
+  source: Source,
+  contributors: readonly CompletionContributor[],
+  evidence: readonly CompletionEvidence[] = [],
+) {
+  return inspectConfiguredCompletionDeclarations(source, contributors, evidence)
+    .manual
+}

package/evidence.ts

@@ -0,0 +1,46 @@
+import type { CompletionEvidence } from "./contributors.ts"
+import {
+  completionSummary,
+  type CompletionFact,
+  type CompletionReader,
+  type CompletionRef,
+} from "./model.ts"
+
+const AMBIGUOUS_EVIDENCE: Readonly<{ fact?: CompletionFact }> = Object.freeze(
+  {},
+)
+
+function derivedEvidence(
+  evidence: readonly CompletionEvidence[],
+  actorId: string,
+  ref: CompletionRef,
+) {
+  let owned: Readonly<{ fact?: CompletionFact }> | undefined
+  for (const provider of evidence) {
+    const result = provider.read(actorId, ref)
+    if (!result) continue
+    if (owned) return AMBIGUOUS_EVIDENCE
+    owned = result
+  }
+  return owned
+}
+
+/** Overlay provider-owned evidence without copying it into Completion State. */
+export function completionReader(
+  manual: CompletionReader,
+  evidence: readonly CompletionEvidence[],
+): CompletionReader {
+  const read = (
+    actorId: string,
+    ref: CompletionRef,
+  ): CompletionFact | undefined => {
+    const derived = derivedEvidence(evidence, actorId, ref)
+    return derived ? derived.fact : manual.read(actorId, ref)
+  }
+  return Object.freeze({
+    read,
+    summary(actorId, refs) {
+      return completionSummary(refs, (ref) => read(actorId, ref))
+    },
+  })
+}