@mmon-co/ncept-core 0.0.0-stage → 0.2.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.
- package/LICENSE +21 -0
- package/README.md +35 -2
- package/dist/digest.d.ts +9 -0
- package/dist/digest.js +40 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.js +7 -0
- package/dist/observations.d.ts +181 -0
- package/dist/observations.js +95 -0
- package/dist/patch/capabilities.d.ts +42 -0
- package/dist/patch/capabilities.js +51 -0
- package/dist/patch/compile.d.ts +43 -0
- package/dist/patch/compile.js +285 -0
- package/dist/patch/copy.d.ts +12 -0
- package/dist/patch/copy.js +142 -0
- package/dist/patch/errors.d.ts +5 -0
- package/dist/patch/errors.js +7 -0
- package/dist/patch/guidance.d.ts +52 -0
- package/dist/patch/guidance.js +109 -0
- package/dist/patch/index.d.ts +16 -0
- package/dist/patch/index.js +16 -0
- package/dist/patch/metadata.d.ts +36 -0
- package/dist/patch/metadata.js +188 -0
- package/dist/patch/model.d.ts +291 -0
- package/dist/patch/model.js +27 -0
- package/dist/patch/project.d.ts +2 -0
- package/dist/patch/project.js +82 -0
- package/dist/patch/reify.d.ts +18 -0
- package/dist/patch/reify.js +237 -0
- package/dist/patch/release.d.ts +49 -0
- package/dist/patch/release.js +268 -0
- package/dist/patch/resolve.d.ts +36 -0
- package/dist/patch/resolve.js +685 -0
- package/dist/patch/route.d.ts +10 -0
- package/dist/patch/route.js +33 -0
- package/dist/patch/select.d.ts +21 -0
- package/dist/patch/select.js +328 -0
- package/dist/patch/translation.d.ts +65 -0
- package/dist/patch/translation.js +213 -0
- package/dist/patch/variants.d.ts +49 -0
- package/dist/patch/variants.js +146 -0
- package/dist/patch/view.d.ts +11 -0
- package/dist/patch/view.js +4 -0
- package/dist/profile.d.ts +61 -0
- package/dist/profile.js +75 -0
- package/dist/run.d.ts +98 -0
- package/dist/run.js +130 -0
- package/dist/theory/index.d.ts +6 -0
- package/dist/theory/index.js +6 -0
- package/dist/theory/migrations.d.ts +47 -0
- package/dist/theory/migrations.js +95 -0
- package/dist/theory/modes.d.ts +77 -0
- package/dist/theory/modes.js +1 -0
- package/dist/theory/path.d.ts +33 -0
- package/dist/theory/path.js +43 -0
- package/dist/theory/release.d.ts +12 -0
- package/dist/theory/release.js +20 -0
- package/dist/theory/skills.d.ts +20 -0
- package/dist/theory/skills.js +20 -0
- package/dist/theory/speaker.d.ts +13 -0
- package/dist/theory/speaker.js +13 -0
- package/dist/theory/theory.d.ts +318 -0
- package/dist/theory/theory.js +43 -0
- package/dist/version_range.d.ts +3 -0
- package/dist/version_range.js +10 -0
- package/package.json +63 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 mmon-co
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,36 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Core
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
`@mmon-co/ncept-core` owns the portable data and algorithms shared by mmon hosts:
|
|
4
|
+
|
|
5
|
+
- **Patches**: content-addressed revisions, Nodes, Edges, Materials, metadata, composition, release resolution and validation. Revision digests identify immutable content.
|
|
6
|
+
- **The observation log and Profile**: observation envelopes with opaque Theory payloads, portable Mission/run records, log merging and closed Patch bundles. Core validates structure, not the pedagogical meaning of evidence.
|
|
7
|
+
- **The Theory interface**: version/range resolution, state folds, projections, Session modes and Programs. A Program yields reads, writes and judgments for a host to execute; Core does not call a model.
|
|
8
|
+
|
|
9
|
+
Hosts own storage, attachment bytes, authentication, Hub transport, scheduling, model calls, tool execution and UI. Theories own learner-state interpretation, pedagogy and Skills. The default implementation is the separate `@mmon-co/ncept-default-theory` package; Core does not depend on it.
|
|
10
|
+
|
|
11
|
+
## Use
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
npm install @mmon-co/ncept-core
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
```js
|
|
18
|
+
import { emptyPatch, contentDigest } from "@mmon-co/ncept-core";
|
|
19
|
+
|
|
20
|
+
console.log(contentDigest(emptyPatch()));
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
The root exports the public operations and types. Focused exports are `/digest`, `/patch`, `/observations`, `/profile`, `/theory`, `/theory/path` and `/theory/speaker`. Node.js 20.19+ is supported. Published exports are ESM JavaScript with TypeScript declarations, usable without a TypeScript runtime.
|
|
24
|
+
|
|
25
|
+
## Build in the source repository
|
|
26
|
+
|
|
27
|
+
```sh
|
|
28
|
+
bun install --frozen-lockfile
|
|
29
|
+
bun run --cwd packages/core build
|
|
30
|
+
cd packages/core
|
|
31
|
+
npm pack --dry-run
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
`prepack` rebuilds `dist/`. The package contains only `dist/`, this README, `LICENSE` and its manifest. Repository tsconfig paths resolve workspace imports directly to source; they are not aliases for any former package name.
|
|
35
|
+
|
|
36
|
+
MIT licensed; see [LICENSE](LICENSE).
|
package/dist/digest.d.ts
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/** Pure sha256 hex so Core's digests run in Convex functions and browsers, not only Node. */
|
|
2
|
+
export declare function sha256Hex(text: string): string;
|
|
3
|
+
/** Shared content identity for JSON values. Owners choose which data is content. */
|
|
4
|
+
export type ContentDigest = `sha256:${string}`;
|
|
5
|
+
/** SHA-256 of raw bytes, not JSON; text attachments supply their UTF-8 encoding. */
|
|
6
|
+
export declare function attachmentDigest(bytes: Uint8Array): ContentDigest;
|
|
7
|
+
export declare function canonicalJson(value: unknown): string;
|
|
8
|
+
export declare function contentDigest(value: unknown): ContentDigest;
|
|
9
|
+
export declare function isContentDigest(value: unknown): value is ContentDigest;
|
package/dist/digest.js
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import { sha256 } from "@noble/hashes/sha2.js";
|
|
2
|
+
import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils.js";
|
|
3
|
+
/** Pure sha256 hex so Core's digests run in Convex functions and browsers, not only Node. */
|
|
4
|
+
export function sha256Hex(text) {
|
|
5
|
+
return bytesToHex(sha256(utf8ToBytes(text)));
|
|
6
|
+
}
|
|
7
|
+
/** SHA-256 of raw bytes, not JSON; text attachments supply their UTF-8 encoding. */
|
|
8
|
+
export function attachmentDigest(bytes) {
|
|
9
|
+
return `sha256:${bytesToHex(sha256(bytes))}`;
|
|
10
|
+
}
|
|
11
|
+
function canonicalValue(value) {
|
|
12
|
+
if (value === null || typeof value === "boolean" || typeof value === "string")
|
|
13
|
+
return JSON.stringify(value);
|
|
14
|
+
if (typeof value === "number") {
|
|
15
|
+
if (!Number.isFinite(value))
|
|
16
|
+
throw new TypeError("canonical content cannot contain non-finite numbers");
|
|
17
|
+
return JSON.stringify(value);
|
|
18
|
+
}
|
|
19
|
+
if (Array.isArray(value))
|
|
20
|
+
return `[${Array.from(value, canonicalValue).join(",")}]`;
|
|
21
|
+
if (typeof value === "object") {
|
|
22
|
+
const prototype = Object.getPrototypeOf(value);
|
|
23
|
+
if (prototype !== Object.prototype && prototype !== null)
|
|
24
|
+
throw new TypeError("canonical content must contain plain JSON objects");
|
|
25
|
+
return `{${Object.entries(value)
|
|
26
|
+
.sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
|
|
27
|
+
.map(([key, entry]) => `${JSON.stringify(key)}:${canonicalValue(entry)}`)
|
|
28
|
+
.join(",")}}`;
|
|
29
|
+
}
|
|
30
|
+
throw new TypeError(`canonical content cannot contain ${typeof value}`);
|
|
31
|
+
}
|
|
32
|
+
export function canonicalJson(value) {
|
|
33
|
+
return canonicalValue(value);
|
|
34
|
+
}
|
|
35
|
+
export function contentDigest(value) {
|
|
36
|
+
return `sha256:${sha256Hex(canonicalJson(value))}`;
|
|
37
|
+
}
|
|
38
|
+
export function isContentDigest(value) {
|
|
39
|
+
return typeof value === "string" && /^sha256:[a-f0-9]{64}$/.test(value);
|
|
40
|
+
}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
export { attachmentDigest, canonicalJson, contentDigest, isContentDigest, type ContentDigest } from "./digest.js";
|
|
2
|
+
export * from "./patch/index.js";
|
|
3
|
+
export * from "./run.js";
|
|
4
|
+
export { satisfiesVersionRange, validVersionRange } from "./version_range.js";
|
|
5
|
+
export * from "./profile.js";
|
|
6
|
+
export * from "./observations.js";
|
|
7
|
+
export * from "./theory/index.js";
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
export { attachmentDigest, canonicalJson, contentDigest, isContentDigest } from "./digest.js";
|
|
2
|
+
export * from "./patch/index.js";
|
|
3
|
+
export * from "./run.js";
|
|
4
|
+
export { satisfiesVersionRange, validVersionRange } from "./version_range.js";
|
|
5
|
+
export * from "./profile.js";
|
|
6
|
+
export * from "./observations.js";
|
|
7
|
+
export * from "./theory/index.js";
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
import type { Speaker } from "./theory/speaker.js";
|
|
2
|
+
import { type ExactPatchRef, type NodeId, type ResolvedGraph } from "./patch/index.js";
|
|
3
|
+
export type ObservationId = `obs-${string}`;
|
|
4
|
+
export type SurfaceId = `surface-${string}`;
|
|
5
|
+
export type ObjectId = `object-${string}`;
|
|
6
|
+
export type TheoryRef = Readonly<{
|
|
7
|
+
theory: string;
|
|
8
|
+
version: string;
|
|
9
|
+
}>;
|
|
10
|
+
/** Host-computed relation to selected history; not authored evidence. */
|
|
11
|
+
export type SourceStanding = "selected" | "abandoned" | "unscoped";
|
|
12
|
+
/** A host-resolved local day (possibly truncated at a zone-change floor); [start, end). */
|
|
13
|
+
export type LearnerDay = Readonly<{
|
|
14
|
+
id: string;
|
|
15
|
+
start: string;
|
|
16
|
+
end: string;
|
|
17
|
+
}>;
|
|
18
|
+
export interface Observation<P = unknown> {
|
|
19
|
+
/** Host-read day boundary, like standing; absent until the browser reports a zone. */
|
|
20
|
+
readonly learnerDay?: LearnerDay;
|
|
21
|
+
readonly standing?: SourceStanding;
|
|
22
|
+
/** Host-read lifecycle of a review card, not authored evidence; absent for other sources. */
|
|
23
|
+
readonly materialPresent?: boolean;
|
|
24
|
+
readonly id: ObservationId;
|
|
25
|
+
readonly at: string;
|
|
26
|
+
readonly by: "platform" | TheoryRef;
|
|
27
|
+
/** Source scope, distinct from theory attribution in nodes. */
|
|
28
|
+
readonly about?: readonly NodeId[];
|
|
29
|
+
readonly nodes?: readonly NodeId[];
|
|
30
|
+
readonly cites?: readonly ObservationId[];
|
|
31
|
+
readonly surface?: SurfaceId;
|
|
32
|
+
readonly supersedes?: ObservationId;
|
|
33
|
+
readonly payload: P;
|
|
34
|
+
}
|
|
35
|
+
export type ObservationWrite<P = unknown> = Omit<Observation<P>, "id" | "at" | "by" | "standing" | "materialPresent" | "learnerDay"> & {
|
|
36
|
+
readonly at?: string;
|
|
37
|
+
};
|
|
38
|
+
export type TranscriptSpan = Readonly<{
|
|
39
|
+
from: string;
|
|
40
|
+
to: string;
|
|
41
|
+
}>;
|
|
42
|
+
export interface Transcript {
|
|
43
|
+
readonly surface: SurfaceId;
|
|
44
|
+
readonly span: TranscriptSpan;
|
|
45
|
+
readonly turns: readonly {
|
|
46
|
+
readonly id: string;
|
|
47
|
+
readonly speaker: Speaker;
|
|
48
|
+
readonly at: string;
|
|
49
|
+
readonly text: string;
|
|
50
|
+
readonly toolNames?: readonly string[];
|
|
51
|
+
}[];
|
|
52
|
+
}
|
|
53
|
+
export type PlatformEvent = {
|
|
54
|
+
readonly kind: "day.ended";
|
|
55
|
+
readonly day: LearnerDay;
|
|
56
|
+
readonly about: readonly NodeId[];
|
|
57
|
+
} | {
|
|
58
|
+
readonly kind: "surface.open";
|
|
59
|
+
readonly surface: SurfaceId;
|
|
60
|
+
readonly format: string;
|
|
61
|
+
readonly about: readonly NodeId[];
|
|
62
|
+
} | {
|
|
63
|
+
readonly kind: "surface.close";
|
|
64
|
+
readonly surface: SurfaceId;
|
|
65
|
+
readonly about: readonly NodeId[];
|
|
66
|
+
readonly span: TranscriptSpan;
|
|
67
|
+
} | {
|
|
68
|
+
readonly kind: "outcome";
|
|
69
|
+
readonly material?: {
|
|
70
|
+
readonly playground: string;
|
|
71
|
+
readonly id: string;
|
|
72
|
+
};
|
|
73
|
+
readonly surface: SurfaceId;
|
|
74
|
+
readonly at: string;
|
|
75
|
+
readonly about?: readonly NodeId[];
|
|
76
|
+
readonly cites?: readonly ObservationId[];
|
|
77
|
+
readonly payload: unknown;
|
|
78
|
+
} | {
|
|
79
|
+
readonly kind: "feature.used";
|
|
80
|
+
readonly operation: string;
|
|
81
|
+
readonly at: string;
|
|
82
|
+
readonly about: readonly NodeId[];
|
|
83
|
+
} | {
|
|
84
|
+
readonly kind: "object.put";
|
|
85
|
+
readonly object: ObjectId;
|
|
86
|
+
readonly meta: ObjectMeta;
|
|
87
|
+
readonly surface?: SurfaceId;
|
|
88
|
+
} | {
|
|
89
|
+
readonly kind: "patch.changed";
|
|
90
|
+
readonly from: ExactPatchRef;
|
|
91
|
+
readonly to: ExactPatchRef;
|
|
92
|
+
readonly successors?: Readonly<Partial<Record<NodeId, readonly NodeId[]>>>;
|
|
93
|
+
readonly cites?: readonly ObservationId[];
|
|
94
|
+
} | {
|
|
95
|
+
readonly kind: "mission";
|
|
96
|
+
readonly text: string;
|
|
97
|
+
};
|
|
98
|
+
export type ObjectMeta = Readonly<{
|
|
99
|
+
name: string;
|
|
100
|
+
mime: string;
|
|
101
|
+
bytes: number;
|
|
102
|
+
}>;
|
|
103
|
+
export type ObjectContent = {
|
|
104
|
+
readonly kind: "text";
|
|
105
|
+
readonly text: string;
|
|
106
|
+
} | {
|
|
107
|
+
readonly kind: "bytes";
|
|
108
|
+
readonly base64: string;
|
|
109
|
+
};
|
|
110
|
+
export type Revision = Readonly<{
|
|
111
|
+
patch: ExactPatchRef;
|
|
112
|
+
graph: ResolvedGraph;
|
|
113
|
+
}>;
|
|
114
|
+
export type ObservationSelector = {
|
|
115
|
+
readonly about?: readonly NodeId[];
|
|
116
|
+
readonly nodes?: readonly NodeId[];
|
|
117
|
+
readonly surface?: SurfaceId;
|
|
118
|
+
readonly by?: "platform" | TheoryRef;
|
|
119
|
+
};
|
|
120
|
+
/** Reads return effective evidence in stable recording order (including late source evidence), not journal cursors. */
|
|
121
|
+
export type Selector = {
|
|
122
|
+
readonly kind: "patch";
|
|
123
|
+
readonly ref?: ExactPatchRef;
|
|
124
|
+
} | ({
|
|
125
|
+
readonly kind: "observations";
|
|
126
|
+
} & ObservationSelector) | {
|
|
127
|
+
readonly kind: "transcript";
|
|
128
|
+
readonly surface: SurfaceId;
|
|
129
|
+
readonly span?: TranscriptSpan;
|
|
130
|
+
} | {
|
|
131
|
+
readonly kind: "object";
|
|
132
|
+
readonly object: ObjectId;
|
|
133
|
+
} | {
|
|
134
|
+
readonly kind: "objects";
|
|
135
|
+
};
|
|
136
|
+
export type JsonSchema = Readonly<Record<string, unknown>>;
|
|
137
|
+
/** A grader judges independent criteria; native evidence is addressed by a selected learner message. */
|
|
138
|
+
export type Grader = "decision" | {
|
|
139
|
+
readonly model: string;
|
|
140
|
+
};
|
|
141
|
+
export interface AssessmentRequest {
|
|
142
|
+
readonly kind: "assess";
|
|
143
|
+
readonly grader: Grader;
|
|
144
|
+
readonly input: Readonly<Record<string, unknown>>;
|
|
145
|
+
readonly criteria: Readonly<Record<string, string>>;
|
|
146
|
+
readonly message?: string;
|
|
147
|
+
}
|
|
148
|
+
export type Request = AssessmentRequest | {
|
|
149
|
+
readonly kind: "read";
|
|
150
|
+
readonly select: Selector;
|
|
151
|
+
} | {
|
|
152
|
+
readonly kind: "judge";
|
|
153
|
+
readonly instruction: string;
|
|
154
|
+
readonly input: unknown;
|
|
155
|
+
readonly schema: JsonSchema;
|
|
156
|
+
} | {
|
|
157
|
+
readonly kind: "write";
|
|
158
|
+
readonly observation: ObservationWrite;
|
|
159
|
+
};
|
|
160
|
+
export type Program<T> = Generator<Request, T, unknown>;
|
|
161
|
+
export declare const read: {
|
|
162
|
+
patch: (ref?: ExactPatchRef) => Program<Revision>;
|
|
163
|
+
observations: (select?: ObservationSelector) => Program<readonly Observation[]>;
|
|
164
|
+
transcript: (surface: SurfaceId, span?: TranscriptSpan) => Program<Transcript>;
|
|
165
|
+
object: (object: ObjectId) => Program<ObjectContent>;
|
|
166
|
+
objects: () => Program<readonly (ObjectMeta & {
|
|
167
|
+
readonly id: ObjectId;
|
|
168
|
+
})[]>;
|
|
169
|
+
};
|
|
170
|
+
export declare function judge<T>(instruction: string, input: unknown, schema: JsonSchema, parse: (raw: unknown) => T): Program<T>;
|
|
171
|
+
export declare function write<P>(observation: ObservationWrite<P>): Program<ObservationId>;
|
|
172
|
+
export declare function isObservationId(value: unknown): value is ObservationId;
|
|
173
|
+
/** Core checks only the envelope. Payload vocabulary and meaning belong to the consuming Theory. */
|
|
174
|
+
export declare function isObservation(value: unknown): value is Observation;
|
|
175
|
+
/** Chronology of what observations record. It is not their acceptance order: identity carries no order,
|
|
176
|
+
* and the host supplies the logically ordered sequence a theory reads.
|
|
177
|
+
*/
|
|
178
|
+
export declare function compareObservations(left: Observation, right: Observation): number;
|
|
179
|
+
export declare function isObservationTimestamp(value: unknown): value is string;
|
|
180
|
+
/** Collapse supplied supersession chains; evidence selection belongs to the consuming theory. */
|
|
181
|
+
export declare function effectiveObservations(observations: readonly Observation[], now: string): readonly Observation[];
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
import { isNodeId } from "./patch/index.js";
|
|
2
|
+
function* readValue(select) {
|
|
3
|
+
return yield { kind: "read", select };
|
|
4
|
+
}
|
|
5
|
+
export const read = {
|
|
6
|
+
patch: (ref) => readValue({ kind: "patch", ...(ref === undefined ? {} : { ref }) }),
|
|
7
|
+
observations: (select = {}) => readValue({ kind: "observations", ...select }),
|
|
8
|
+
transcript: (surface, span) => readValue({ kind: "transcript", surface, ...(span === undefined ? {} : { span }) }),
|
|
9
|
+
object: (object) => readValue({ kind: "object", object }),
|
|
10
|
+
objects: () => readValue({ kind: "objects" }),
|
|
11
|
+
};
|
|
12
|
+
export function* judge(instruction, input, schema, parse) {
|
|
13
|
+
return parse(yield { kind: "judge", instruction, input, schema });
|
|
14
|
+
}
|
|
15
|
+
export function* write(observation) {
|
|
16
|
+
if ("standing" in observation)
|
|
17
|
+
throw new Error("Observation standing is host-assigned read context");
|
|
18
|
+
const id = yield { kind: "write", observation };
|
|
19
|
+
if (!isObservationId(id))
|
|
20
|
+
throw new Error("Write requires a host-assigned observation identity");
|
|
21
|
+
return id;
|
|
22
|
+
}
|
|
23
|
+
export function isObservationId(value) {
|
|
24
|
+
return typeof value === "string" && /^obs-.+/.test(value);
|
|
25
|
+
}
|
|
26
|
+
/** Core checks only the envelope. Payload vocabulary and meaning belong to the consuming Theory. */
|
|
27
|
+
export function isObservation(value) {
|
|
28
|
+
if (!observationObject(value))
|
|
29
|
+
return false;
|
|
30
|
+
const by = value.by;
|
|
31
|
+
const day = value.learnerDay;
|
|
32
|
+
return (isObservationId(value.id) &&
|
|
33
|
+
isObservationTimestamp(value.at) &&
|
|
34
|
+
(by === "platform" || (observationObject(by) && observationText(by.theory) && observationText(by.version))) &&
|
|
35
|
+
Object.hasOwn(value, "payload") &&
|
|
36
|
+
value.payload !== undefined &&
|
|
37
|
+
(value.about === undefined || (Array.isArray(value.about) && value.about.every(isNodeId))) &&
|
|
38
|
+
(value.nodes === undefined || (Array.isArray(value.nodes) && value.nodes.every(isNodeId))) &&
|
|
39
|
+
(value.cites === undefined || (Array.isArray(value.cites) && value.cites.every(isObservationId))) &&
|
|
40
|
+
(value.surface === undefined || (typeof value.surface === "string" && /^surface-.+/.test(value.surface))) &&
|
|
41
|
+
(value.supersedes === undefined || isObservationId(value.supersedes)) &&
|
|
42
|
+
(value.standing === undefined ||
|
|
43
|
+
value.standing === "selected" ||
|
|
44
|
+
value.standing === "abandoned" ||
|
|
45
|
+
value.standing === "unscoped") &&
|
|
46
|
+
(value.materialPresent === undefined || typeof value.materialPresent === "boolean") &&
|
|
47
|
+
(day === undefined ||
|
|
48
|
+
(observationObject(day) &&
|
|
49
|
+
observationText(day.id) &&
|
|
50
|
+
isObservationTimestamp(day.start) &&
|
|
51
|
+
isObservationTimestamp(day.end) &&
|
|
52
|
+
Date.parse(day.start) < Date.parse(day.end))));
|
|
53
|
+
}
|
|
54
|
+
function observationObject(value) {
|
|
55
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
56
|
+
}
|
|
57
|
+
function observationText(value) {
|
|
58
|
+
return typeof value === "string" && value.length > 0;
|
|
59
|
+
}
|
|
60
|
+
/** Chronology of what observations record. It is not their acceptance order: identity carries no order,
|
|
61
|
+
* and the host supplies the logically ordered sequence a theory reads.
|
|
62
|
+
*/
|
|
63
|
+
export function compareObservations(left, right) {
|
|
64
|
+
return Date.parse(left.at) - Date.parse(right.at) || left.id.localeCompare(right.id);
|
|
65
|
+
}
|
|
66
|
+
export function isObservationTimestamp(value) {
|
|
67
|
+
if (typeof value !== "string")
|
|
68
|
+
return false;
|
|
69
|
+
const match = /^(\d{4})-(\d\d)-(\d\d)T(\d\d):(\d\d):(\d\d)(?:\.\d+)?(?:Z|[+-]\d\d:\d\d)$/.exec(value);
|
|
70
|
+
if (match === null || !Number.isFinite(Date.parse(value)))
|
|
71
|
+
return false;
|
|
72
|
+
const year = Number(match[1]);
|
|
73
|
+
const month = Number(match[2]);
|
|
74
|
+
const day = Number(match[3]);
|
|
75
|
+
const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
|
|
76
|
+
const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1];
|
|
77
|
+
return (days !== undefined &&
|
|
78
|
+
day >= 1 &&
|
|
79
|
+
day <= days &&
|
|
80
|
+
Number(match[4]) < 24 &&
|
|
81
|
+
Number(match[5]) < 60 &&
|
|
82
|
+
Number(match[6]) < 60);
|
|
83
|
+
}
|
|
84
|
+
/** Collapse supplied supersession chains; evidence selection belongs to the consuming theory. */
|
|
85
|
+
export function effectiveObservations(observations, now) {
|
|
86
|
+
if (!isObservationTimestamp(now))
|
|
87
|
+
throw new Error("State requires an ISO timestamp");
|
|
88
|
+
const present = observations.filter((observation) => {
|
|
89
|
+
if (!isObservationTimestamp(observation.at))
|
|
90
|
+
throw new Error(`Invalid observation timestamp: ${observation.id}`);
|
|
91
|
+
return Date.parse(observation.at) <= Date.parse(now);
|
|
92
|
+
});
|
|
93
|
+
const superseded = new Set(present.flatMap(({ supersedes }) => (supersedes === undefined ? [] : [supersedes])));
|
|
94
|
+
return present.filter(({ id }) => !superseded.has(id));
|
|
95
|
+
}
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import { type ResolvedGuidanceEntry } from "./guidance.js";
|
|
2
|
+
import type { MaterialId, NodeId, ResolvedGraph } from "./model.js";
|
|
3
|
+
export declare const PEDAGOGY_SKILLS_PROPERTY = "pedagogy:skills";
|
|
4
|
+
export declare const PEDAGOGY_TOOLS_PROPERTY = "pedagogy:tools";
|
|
5
|
+
export declare const CAPABILITY_PROPERTIES: readonly ["pedagogy:skills", "pedagogy:tools"];
|
|
6
|
+
/** Additive, authored Skill text; names are local to their contributing Patch. */
|
|
7
|
+
export interface PatchSkillEntry {
|
|
8
|
+
readonly name: string;
|
|
9
|
+
readonly description: string;
|
|
10
|
+
readonly text: string;
|
|
11
|
+
readonly nodes?: readonly NodeId[];
|
|
12
|
+
}
|
|
13
|
+
/** The command schema and implementation remain in this Patch's packaged applet. */
|
|
14
|
+
export interface PatchToolEntry {
|
|
15
|
+
readonly name: string;
|
|
16
|
+
readonly description: string;
|
|
17
|
+
readonly applet: MaterialId;
|
|
18
|
+
readonly command: string;
|
|
19
|
+
readonly nodes?: readonly NodeId[];
|
|
20
|
+
}
|
|
21
|
+
/** Also carried by Mission revisions before materialization as tag Metadata. */
|
|
22
|
+
export interface PatchCapabilities {
|
|
23
|
+
readonly skills?: readonly PatchSkillEntry[];
|
|
24
|
+
readonly tools?: readonly PatchToolEntry[];
|
|
25
|
+
}
|
|
26
|
+
export interface ResolvedPatchCapability<T> {
|
|
27
|
+
readonly entry: T;
|
|
28
|
+
readonly origin: ResolvedGuidanceEntry["origin"];
|
|
29
|
+
}
|
|
30
|
+
export interface ResolvedPatchCapabilities {
|
|
31
|
+
readonly skills: readonly ResolvedPatchCapability<PatchSkillEntry>[];
|
|
32
|
+
readonly tools: readonly ResolvedPatchCapability<PatchToolEntry>[];
|
|
33
|
+
}
|
|
34
|
+
/** Portable vocabulary only; host Skill catalog names and applet authority are separate. */
|
|
35
|
+
export declare function isPatchSkillEntries(value: unknown): value is readonly PatchSkillEntry[];
|
|
36
|
+
export declare function isPatchToolEntries(value: unknown): value is readonly PatchToolEntry[];
|
|
37
|
+
/**
|
|
38
|
+
* Additions never replace one another, even with the same name. Within each kind, a
|
|
39
|
+
* contribution is identified by metadataSet, source and entryIndex, not by name or
|
|
40
|
+
* applicable subjects (which can differ across Nodes in a Session union).
|
|
41
|
+
*/
|
|
42
|
+
export declare function nodePatchCapabilities(graph: ResolvedGraph, node: NodeId): ResolvedPatchCapabilities;
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
import { nodeMetadataCascade } from "./guidance.js";
|
|
2
|
+
import { isMaterialMeta } from "./metadata.js";
|
|
3
|
+
import { isNodeId } from "./release.js";
|
|
4
|
+
export const PEDAGOGY_SKILLS_PROPERTY = "pedagogy:skills";
|
|
5
|
+
export const PEDAGOGY_TOOLS_PROPERTY = "pedagogy:tools";
|
|
6
|
+
export const CAPABILITY_PROPERTIES = [PEDAGOGY_SKILLS_PROPERTY, PEDAGOGY_TOOLS_PROPERTY];
|
|
7
|
+
function nonblank(value) {
|
|
8
|
+
return typeof value === "string" && value.trim() !== "";
|
|
9
|
+
}
|
|
10
|
+
function object(value) {
|
|
11
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
12
|
+
}
|
|
13
|
+
function capabilityEntries(value, fields, valid) {
|
|
14
|
+
return (Array.isArray(value) &&
|
|
15
|
+
isMaterialMeta({ entries: value }) &&
|
|
16
|
+
value.every((entry) => {
|
|
17
|
+
if (!object(entry))
|
|
18
|
+
return false;
|
|
19
|
+
const item = entry;
|
|
20
|
+
return (Object.keys(item).every((key) => ["name", "description", "nodes", ...fields].includes(key)) &&
|
|
21
|
+
nonblank(item.name) &&
|
|
22
|
+
nonblank(item.description) &&
|
|
23
|
+
!/[\r\n]/.test(item.description) &&
|
|
24
|
+
(!("nodes" in item) || (Array.isArray(item.nodes) && item.nodes.every(isNodeId))) &&
|
|
25
|
+
valid(item));
|
|
26
|
+
}));
|
|
27
|
+
}
|
|
28
|
+
/** Portable vocabulary only; host Skill catalog names and applet authority are separate. */
|
|
29
|
+
export function isPatchSkillEntries(value) {
|
|
30
|
+
return capabilityEntries(value, ["text"], (entry) => nonblank(entry.text));
|
|
31
|
+
}
|
|
32
|
+
export function isPatchToolEntries(value) {
|
|
33
|
+
return capabilityEntries(value, ["applet", "command"], (entry) => nonblank(entry.applet) && nonblank(entry.command));
|
|
34
|
+
}
|
|
35
|
+
function resolvedCapabilities(graph, node, property, valid) {
|
|
36
|
+
return nodeMetadataCascade(graph, node, property, (value) => (valid(value) ? value : []))
|
|
37
|
+
.filter(({ value }) => value.nodes === undefined || value.nodes.includes(node))
|
|
38
|
+
.sort((a, b) => Number(a.value.nodes !== undefined) - Number(b.value.nodes !== undefined))
|
|
39
|
+
.map(({ value, origin }) => ({ entry: value, origin }));
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* Additions never replace one another, even with the same name. Within each kind, a
|
|
43
|
+
* contribution is identified by metadataSet, source and entryIndex, not by name or
|
|
44
|
+
* applicable subjects (which can differ across Nodes in a Session union).
|
|
45
|
+
*/
|
|
46
|
+
export function nodePatchCapabilities(graph, node) {
|
|
47
|
+
return {
|
|
48
|
+
skills: resolvedCapabilities(graph, node, PEDAGOGY_SKILLS_PROPERTY, isPatchSkillEntries),
|
|
49
|
+
tools: resolvedCapabilities(graph, node, PEDAGOGY_TOOLS_PROPERTY, isPatchToolEntries),
|
|
50
|
+
};
|
|
51
|
+
}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import type { ClosedPatchBundle, EdgeId, ExactPatchRef, GraphCompilationInput, PatchContent, PatchId, PatchMetadata, NodeId, ResolvedGraph, SemanticDelta, VisualGraph } from "./model.js";
|
|
2
|
+
export interface GraphDiffCompileReport {
|
|
3
|
+
readonly valid: boolean;
|
|
4
|
+
readonly compiledAgainst: ExactPatchRef;
|
|
5
|
+
readonly cycles: readonly (readonly NodeId[])[];
|
|
6
|
+
readonly danglingEndpoints: readonly {
|
|
7
|
+
readonly edge: EdgeId;
|
|
8
|
+
readonly missing: readonly NodeId[];
|
|
9
|
+
}[];
|
|
10
|
+
readonly missingDisplayLabels: readonly NodeId[];
|
|
11
|
+
readonly roots: readonly NodeId[];
|
|
12
|
+
readonly cone: {
|
|
13
|
+
readonly targets: readonly NodeId[];
|
|
14
|
+
readonly missingTargets: readonly NodeId[];
|
|
15
|
+
readonly nodes: readonly NodeId[];
|
|
16
|
+
readonly edges: readonly EdgeId[];
|
|
17
|
+
readonly coveredRoots: readonly NodeId[];
|
|
18
|
+
};
|
|
19
|
+
readonly highInDegreeThreshold: number;
|
|
20
|
+
readonly highInDegreeNodes: readonly {
|
|
21
|
+
readonly node: NodeId;
|
|
22
|
+
readonly inDegree: number;
|
|
23
|
+
}[];
|
|
24
|
+
}
|
|
25
|
+
export interface CompiledGraphDiff {
|
|
26
|
+
readonly operations: SemanticDelta["operations"];
|
|
27
|
+
readonly citations: PatchMetadata["citations"];
|
|
28
|
+
/** Entity ids removed from the terminal revision's own delta before appending operations. */
|
|
29
|
+
readonly retractions: readonly string[];
|
|
30
|
+
readonly graph: ResolvedGraph;
|
|
31
|
+
readonly report: GraphDiffCompileReport;
|
|
32
|
+
}
|
|
33
|
+
/** A structurally invalid diff still carries the report a proposal tool can return to its Skill. */
|
|
34
|
+
export declare class GraphDiffCompileError extends Error {
|
|
35
|
+
readonly report: GraphDiffCompileReport;
|
|
36
|
+
constructor(report: GraphDiffCompileReport);
|
|
37
|
+
}
|
|
38
|
+
/** Notebook composition is content algebra; accepting against a current pointer belongs to the host. */
|
|
39
|
+
export declare function composePatch(content: PatchContent, operations: SemanticDelta["operations"], citations?: PatchMetadata["citations"], retractions?: readonly string[]): PatchContent;
|
|
40
|
+
export declare function applyGraphDiff(content: PatchContent, diff: CompiledGraphDiff): PatchContent;
|
|
41
|
+
/** Compile a proposed delta against one exact User graph and describe its Mission cone. */
|
|
42
|
+
export declare function compileGraphDiff(bundle: ClosedPatchBundle, operations: SemanticDelta["operations"], targets: readonly NodeId[], citations?: PatchMetadata["citations"], retractions?: readonly string[], selection?: ReadonlyMap<PatchId, ExactPatchRef>): CompiledGraphDiff;
|
|
43
|
+
export declare function compileGraph(input: GraphCompilationInput): VisualGraph;
|