@mark1russell7/stack-placement 0.0.0-bootstrap.0 → 0.1.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 +200 -1
- package/build/add-on.d.ts +12 -0
- package/build/add-on.d.ts.map +1 -0
- package/build/add-on.js +23 -0
- package/build/add-on.js.map +1 -0
- package/build/index.d.ts +277 -0
- package/build/index.d.ts.map +1 -0
- package/build/index.js +477 -0
- package/build/index.js.map +1 -0
- package/build/join-BHqjGNJL.js +157 -0
- package/build/join-BHqjGNJL.js.map +1 -0
- package/build/layer--Zwbckrx.d.ts +73 -0
- package/build/layer--Zwbckrx.d.ts.map +1 -0
- package/build/layer-BSj5LGH9.js +6 -0
- package/build/layer-BSj5LGH9.js.map +1 -0
- package/build/schema.d.ts +21 -0
- package/build/schema.d.ts.map +1 -0
- package/build/schema.js +57 -0
- package/build/schema.js.map +1 -0
- package/package.json +73 -6
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Mark Russell
|
|
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,202 @@
|
|
|
1
1
|
# @mark1russell7/stack-placement
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The placement of the parts of a system stack as a query. A layer gives the candidates of each slot. The package finds the choices that no other choice beats on the expected cost and on the chance that a function works.
|
|
4
|
+
|
|
5
|
+
It is the placement add-on of [`@mark1russell7/system-stack`](../system-stack/README.md). The search comes from `@mark1russell7/strategy-search`.
|
|
6
|
+
|
|
7
|
+
The add-on knows no other add-on. The caller gives the joiners and the measures of the chance and of the bound. A host, a site or a test makes them, for example from [`@mark1russell7/stack-risk`](../stack-risk/README.md) and [`@mark1russell7/stack-spend`](../stack-spend/README.md).
|
|
8
|
+
|
|
9
|
+
Nobody picks a placement by hand. Each choice is a stack, and the front is a result of a query over the candidates. When a price or a chance changes, the front changes.
|
|
10
|
+
|
|
11
|
+
Each function is a plain function with no clock and no network.
|
|
12
|
+
|
|
13
|
+
## The rule
|
|
14
|
+
|
|
15
|
+
A slot is a part that the base stack needs, for example a copy of a program. Each candidate of a slot is a stack fragment that gives that part, with its chances, its costs and its expected cost of a month.
|
|
16
|
+
|
|
17
|
+
A part of two or more candidates, for example a provider or a region, is in a shared fragment. A placed stack has each shared fragment one time. Thus two copies on one provider share one cause of failure, and the chance shows it.
|
|
18
|
+
|
|
19
|
+
The front has each choice that keeps the limits and that no other choice beats. A choice beats a different choice when it is as good on the cost and on the chance, and better on one of them.
|
|
20
|
+
|
|
21
|
+
## The entries
|
|
22
|
+
|
|
23
|
+
| Entry | What it has |
|
|
24
|
+
| --- | --- |
|
|
25
|
+
| `@mark1russell7/stack-placement` | The records of a layer, the placed stack of a choice, the plan, the gate, the join and a sample. |
|
|
26
|
+
| `@mark1russell7/stack-placement/schema` | `placementSchema`, the zod schema of a layer, and `parsePlacement`. |
|
|
27
|
+
| `@mark1russell7/stack-placement/add-on` | `placementAddOn`, the add-on in the form of the layer contract of the core. |
|
|
28
|
+
|
|
29
|
+
The root entry has no schema library. Thus a page that only shows a plan gets no zod.
|
|
30
|
+
|
|
31
|
+
## Install
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
npm install @mark1russell7/stack-placement @mark1russell7/system-stack
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
The examples of this file also use the add-ons of risk and spend for the measures:
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
npm install @mark1russell7/stack-risk @mark1russell7/stack-spend
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## A layer
|
|
44
|
+
|
|
45
|
+
A placement layer has the format `placement/1`. A stack keeps it in `Stack.layers`, with the key `placement/1`.
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
import type { PlacementLayer } from "@mark1russell7/stack-placement";
|
|
49
|
+
|
|
50
|
+
const layer: PlacementLayer = {
|
|
51
|
+
schema: "placement/1",
|
|
52
|
+
part: "send",
|
|
53
|
+
currency: "USD",
|
|
54
|
+
slots: [
|
|
55
|
+
{ id: "copy-a", candidates: [/* one candidate for each offer */] },
|
|
56
|
+
{ id: "copy-b", optional: true, candidates: [/* one candidate for each offer */] },
|
|
57
|
+
],
|
|
58
|
+
shared: [/* one fragment for each provider */],
|
|
59
|
+
limits: { cost: 25, chance: 0.999 },
|
|
60
|
+
};
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
`SAMPLE_PLACEMENT` of the package is a full layer. It has two slots, two candidates for each slot, and two providers. `SAMPLE_BASE` is its base stack.
|
|
64
|
+
|
|
65
|
+
| Field of a layer | What it is |
|
|
66
|
+
| --- | --- |
|
|
67
|
+
| `part` | The `id` of the part to keep in work, for example a function of the system. It is a part of the base stack. |
|
|
68
|
+
| `currency` | The currency of each cost. |
|
|
69
|
+
| `slots` | The slots. Each slot is one stage of the search. |
|
|
70
|
+
| `shared` | The shared fragments. |
|
|
71
|
+
| `limits` | The largest expected cost (`cost`), the largest bound of the cost (`bound`), and the smallest chance (`chance`). |
|
|
72
|
+
|
|
73
|
+
| Field of a slot | What it is |
|
|
74
|
+
| --- | --- |
|
|
75
|
+
| `id` | The `id` of the part of the slot. A part of the base stack names it in a need. |
|
|
76
|
+
| `candidates` | The candidates of the slot. |
|
|
77
|
+
| `optional` | With `true`, a choice can leave the slot empty. |
|
|
78
|
+
|
|
79
|
+
| Field of a candidate | What it is |
|
|
80
|
+
| --- | --- |
|
|
81
|
+
| `key` | The key of the candidate in its slot. |
|
|
82
|
+
| `stack` | The stack fragment. It has the part of the slot, and its layers, for example `risk/1` and `spend/1`. |
|
|
83
|
+
| `cost` | The expected cost of a month. |
|
|
84
|
+
| `uses` | The `id` of each shared fragment that the candidate needs. |
|
|
85
|
+
| `source` | The source of the candidate, for example the `id` of an offer. |
|
|
86
|
+
|
|
87
|
+
## The placed stack
|
|
88
|
+
|
|
89
|
+
`placedStack(layer, stack, choice, joiners)` gives the stack of one choice. `joinStacks` of the core joins the base stack, the chosen candidates and their shared fragments. Each add-on of `joiners` joins its layer.
|
|
90
|
+
|
|
91
|
+
```ts
|
|
92
|
+
import { placedStack, SAMPLE_BASE, SAMPLE_PLACEMENT, SAMPLE_TODAY } from "@mark1russell7/stack-placement";
|
|
93
|
+
import { riskAddOn } from "@mark1russell7/stack-risk/add-on";
|
|
94
|
+
import { spendAddOn } from "@mark1russell7/stack-spend/add-on";
|
|
95
|
+
|
|
96
|
+
const joiners = [riskAddOn({ today: SAMPLE_TODAY }), spendAddOn({ today: SAMPLE_TODAY })];
|
|
97
|
+
const placed = placedStack(SAMPLE_PLACEMENT, SAMPLE_BASE, { "copy-a": "small-x", "copy-b": "small-x" }, joiners);
|
|
98
|
+
// placed.ok === true
|
|
99
|
+
// placed.stack.parts.map((part) => part.id) => ["send", "copy-a", "copy-b", "provider-x"]
|
|
100
|
+
// placed.cost => 10
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
A fault of the choice gives no stack. The codes are `slot-unknown`, `slot-empty`, `candidate-unknown` and `shared-unknown`.
|
|
104
|
+
|
|
105
|
+
## The measures
|
|
106
|
+
|
|
107
|
+
The caller gives the measures in the options of a plan. Each measure gets a placed stack.
|
|
108
|
+
|
|
109
|
+
| Option | What it gives |
|
|
110
|
+
| --- | --- |
|
|
111
|
+
| `chance` | The chance that the part of the layer works: a number, or a `ChanceReading` with the most important parts and the assumed parts. It is necessary. |
|
|
112
|
+
| `bound` | A `BoundReading`: the largest cost of a month, and the part of each service with no bound. A layer with the limit `bound` needs it. |
|
|
113
|
+
| `cost` | The expected cost of a month. The default is the sum of the costs of the chosen candidates and of their shared fragments. |
|
|
114
|
+
|
|
115
|
+
- A chance of NaN tells that the measure cannot decide, for example at the end of a budget of steps. The search counts the choice as unread.
|
|
116
|
+
- A measure that throws a `RangeError` refuses the placed stack. The choice gets the break `measure`.
|
|
117
|
+
- A value out of its range also gets the break `measure`: a chance that is not from 0 to 1, or a negative cost.
|
|
118
|
+
- An error that is not a `RangeError` goes to the caller.
|
|
119
|
+
|
|
120
|
+
This example makes the measures from the add-ons of risk and spend:
|
|
121
|
+
|
|
122
|
+
```ts
|
|
123
|
+
import { RISK_SCHEMA, worksChance } from "@mark1russell7/stack-risk";
|
|
124
|
+
import { monthTotal } from "@mark1russell7/stack-spend";
|
|
125
|
+
import { readLayer, type Stack, type StackJoiner } from "@mark1russell7/system-stack";
|
|
126
|
+
import type { BoundReading, ChanceReading } from "@mark1russell7/stack-placement";
|
|
127
|
+
|
|
128
|
+
const [risk, spend] = joiners;
|
|
129
|
+
|
|
130
|
+
function layerOf<Layer>(stack: Stack, addOn: StackJoiner<Layer>): Layer | undefined {
|
|
131
|
+
const read = readLayer(stack, addOn);
|
|
132
|
+
if (read !== undefined && !read.ok) throw new RangeError(read.errors.join(" "));
|
|
133
|
+
return read?.layer;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
function chance(stack: Stack, part: string): ChanceReading {
|
|
137
|
+
const works = worksChance(layerOf(stack, risk) ?? { schema: RISK_SCHEMA, goals: [] }, stack, part);
|
|
138
|
+
return works.kind === "exact" ? { value: works.value, importance: works.importance, assumed: works.assumed } : { value: Number.NaN };
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
function bound(stack: Stack): BoundReading {
|
|
142
|
+
const layer = layerOf(stack, spend);
|
|
143
|
+
return layer === undefined ? { bounded: 0, open: [] } : monthTotal(layer);
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
## The plan
|
|
148
|
+
|
|
149
|
+
`planPlacement(layer, stack, { joiners, chance, bound })` gives the front of the choices.
|
|
150
|
+
|
|
151
|
+
```ts
|
|
152
|
+
import { planPlacement, SAMPLE_BASE, SAMPLE_PLACEMENT } from "@mark1russell7/stack-placement";
|
|
153
|
+
|
|
154
|
+
const plan = planPlacement(SAMPLE_PLACEMENT, SAMPLE_BASE, { joiners, chance, bound });
|
|
155
|
+
plan.front.map((row) => [row.choice["copy-a"], row.choice["copy-b"], row.cost, row.chance.toFixed(6)]);
|
|
156
|
+
// => [
|
|
157
|
+
// ["small-x", null, 5, "0.989010"],
|
|
158
|
+
// ["small-x", "small-x", 10, "0.998900"],
|
|
159
|
+
// ["small-x", "small-y", 11, "0.999726"],
|
|
160
|
+
// ["small-y", "small-x", 11, "0.999726"],
|
|
161
|
+
// ]
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
Two copies on the provider `provider-x` cost 10 and give 0.998900. A copy on each provider costs 11 and gives 0.999726. The shared provider is the difference.
|
|
165
|
+
|
|
166
|
+
- A space with 2000 choices or less gets a grid of each choice. A larger space gets a seeded genetic search. The option `evaluations` sets the count.
|
|
167
|
+
- A choice that breaks a limit is not on the front. `plan.breaks` counts the choices with each break: `join`, `measure`, `cost`, `bound` and `chance`.
|
|
168
|
+
- Each row has the sources of its candidates and its shared fragments. It also has the reading of the bound measure and the most important parts for the chance.
|
|
169
|
+
- The search compares a cost to 1e-9 and a chance to 1e-12 (`OBJECTIVE_STEPS`). Thus two choices with one true value tie, and the front keeps each.
|
|
170
|
+
|
|
171
|
+
The result is deterministic when each measure is deterministic: one layer, one stack and one set of options give one plan.
|
|
172
|
+
|
|
173
|
+
## The gate
|
|
174
|
+
|
|
175
|
+
`checkPlacement(layer, stack)` gives the faults of a layer for its base stack. An empty list tells that the gate passes.
|
|
176
|
+
|
|
177
|
+
| Code | The fault |
|
|
178
|
+
| --- | --- |
|
|
179
|
+
| `part-unknown` | The part of the layer is not a part of the base stack. |
|
|
180
|
+
| `slot-twice` | Two or more slots have one `id`. |
|
|
181
|
+
| `slot-part` | The `id` of a slot is a part of the base stack. |
|
|
182
|
+
| `slot-unneeded` | No part of the base stack names a slot in a need. It is a warning. |
|
|
183
|
+
| `slot-no-candidate` | A slot has no candidate. |
|
|
184
|
+
| `candidate-twice` | Two or more candidates of a slot have one key. |
|
|
185
|
+
| `candidate-part` | The stack of a candidate has no part with the `id` of its slot. |
|
|
186
|
+
| `cost-range` | A cost is not a finite number of 0 or more. |
|
|
187
|
+
| `shared-twice` | Two or more shared fragments have one `id`. |
|
|
188
|
+
| `shared-unknown` | A candidate uses a shared fragment that the layer does not have. |
|
|
189
|
+
| `shared-unused` | No candidate uses a shared fragment. It is a warning. |
|
|
190
|
+
| `limit-range` | A limit of cost is less than 0, or the limit of chance is not from 0 to 1. |
|
|
191
|
+
|
|
192
|
+
The gate does not examine the layers of a fragment or of the base stack. The gates of their add-ons examine each placed stack. The gate does not compare the currency of the layer with a different layer. The measures of the caller do it when it is necessary.
|
|
193
|
+
|
|
194
|
+
The base stack is not whole before a placement. A part of the base names each slot in a need, and the base has no part for a slot. Thus `checkStack` of the core gives the fault `need-part` for each slot of the base stack. A placed stack has the part of each slot with a candidate. An empty optional slot has no part, and the chance counts that part as down.
|
|
195
|
+
|
|
196
|
+
## The add-on
|
|
197
|
+
|
|
198
|
+
`placementAddOn()` gives the add-on for `checkStackLayers` and `joinStacks` of the core. Its `join` is `joinPlacement`: the slots and the shared fragments of each fragment, with one part, one currency and one value for each limit.
|
|
199
|
+
|
|
200
|
+
## License
|
|
201
|
+
|
|
202
|
+
MIT
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { i as PlacementLayer } from "./layer--Zwbckrx.js";
|
|
2
|
+
import { StackJoiner } from "@mark1russell7/system-stack";
|
|
3
|
+
/**
|
|
4
|
+
* This function gives the placement add-on.
|
|
5
|
+
*
|
|
6
|
+
* - `schema` is `placement/1`, the key of the layer in `Stack.layers`.
|
|
7
|
+
* - `parse` is `parsePlacement`.
|
|
8
|
+
* - `check` is the gate `checkPlacement`.
|
|
9
|
+
* - `join` is `joinPlacement`. It joins the placement layers of the fragments of a stack.
|
|
10
|
+
*/
|
|
11
|
+
export declare function placementAddOn(): StackJoiner<PlacementLayer>;
|
|
12
|
+
//# sourceMappingURL=add-on.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"add-on.d.ts","names":[],"sources":["../src/add-on.ts"],"mappings":";;;;;;;;;;wBAiBgB,kBAAkB,YAAY"}
|
package/build/add-on.js
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import { r as checkPlacement, t as joinPlacement } from "./join-BHqjGNJL.js";
|
|
2
|
+
import { t as PLACEMENT_SCHEMA } from "./layer-BSj5LGH9.js";
|
|
3
|
+
import { parsePlacement } from "./schema.js";
|
|
4
|
+
// src/add-on.ts
|
|
5
|
+
/**
|
|
6
|
+
* This function gives the placement add-on.
|
|
7
|
+
*
|
|
8
|
+
* - `schema` is `placement/1`, the key of the layer in `Stack.layers`.
|
|
9
|
+
* - `parse` is `parsePlacement`.
|
|
10
|
+
* - `check` is the gate `checkPlacement`.
|
|
11
|
+
* - `join` is `joinPlacement`. It joins the placement layers of the fragments of a stack.
|
|
12
|
+
*/
|
|
13
|
+
function placementAddOn() {
|
|
14
|
+
return {
|
|
15
|
+
schema: PLACEMENT_SCHEMA,
|
|
16
|
+
parse: parsePlacement,
|
|
17
|
+
check: checkPlacement,
|
|
18
|
+
join: joinPlacement
|
|
19
|
+
};
|
|
20
|
+
}
|
|
21
|
+
export { placementAddOn };
|
|
22
|
+
|
|
23
|
+
//# sourceMappingURL=add-on.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"add-on.js","names":[],"sources":["../src/add-on.ts"],"sourcesContent":["import type { StackJoiner } from \"@mark1russell7/system-stack\";\nimport { checkPlacement } from \"./check.ts\";\nimport { joinPlacement } from \"./join.ts\";\nimport { PLACEMENT_SCHEMA, type PlacementLayer } from \"./layer.ts\";\nimport { parsePlacement } from \"./schema.ts\";\n\n// The placement add-on in the form of the layer contract. A host gives it to `checkStackLayers` and to `joinStacks` of the core.\n// This entry has the schema library, so the root entry does not import it.\n\n/**\n * This function gives the placement add-on.\n *\n * - `schema` is `placement/1`, the key of the layer in `Stack.layers`.\n * - `parse` is `parsePlacement`.\n * - `check` is the gate `checkPlacement`.\n * - `join` is `joinPlacement`. It joins the placement layers of the fragments of a stack.\n */\nexport function placementAddOn(): StackJoiner<PlacementLayer> {\n return { schema: PLACEMENT_SCHEMA, parse: parsePlacement, check: checkPlacement, join: joinPlacement };\n}\n"],"mappings":";;;;;;;;;;;;AAiBA,SAAgB,iBAA8C;CAC5D,OAAO;EAAE,QAAQ;EAAkB,OAAO;EAAgB,OAAO;EAAgB,MAAM;CAAc;AACvG"}
|
package/build/index.d.ts
ADDED
|
@@ -0,0 +1,277 @@
|
|
|
1
|
+
import { a as PlacementLimits, i as PlacementLayer, n as Choice, o as Shared, r as PLACEMENT_SCHEMA, s as Slot, t as Candidate } from "./layer--Zwbckrx.js";
|
|
2
|
+
import { Fault, LayerJoiner, LayerParse, LayerPiece, Stack, StackJoinFinding } from "@mark1russell7/system-stack";
|
|
3
|
+
import { Objective, SweepCounts } from "@mark1russell7/strategy-search";
|
|
4
|
+
import { StrategyConfig, StrategySpace } from "@mark1russell7/strategy-space";
|
|
5
|
+
/**
|
|
6
|
+
* These are the codes of the faults of a choice. Each one is an error.
|
|
7
|
+
*
|
|
8
|
+
* - `slot-unknown`: the choice names a slot that the layer does not have.
|
|
9
|
+
* - `slot-empty`: the choice leaves a slot empty, and the slot is not optional.
|
|
10
|
+
* - `candidate-unknown`: the choice names a key that the slot does not have.
|
|
11
|
+
* - `shared-unknown`: a chosen candidate uses a shared fragment that the layer does not have.
|
|
12
|
+
*/
|
|
13
|
+
export declare const CHOICE_CODES: readonly ["slot-unknown", "slot-empty", "candidate-unknown", "shared-unknown"];
|
|
14
|
+
/** A code of `CHOICE_CODES`. */
|
|
15
|
+
export type ChoiceCode = (typeof CHOICE_CODES)[number];
|
|
16
|
+
/** The name of the fragment of the base stack in a join. */
|
|
17
|
+
export declare const BASE_FRAGMENT = "base";
|
|
18
|
+
/** This function gives the name of the fragment of the chosen candidate of a slot in a join. */
|
|
19
|
+
export declare function slotFragment(slot: string): string;
|
|
20
|
+
/** This function gives the name of a shared fragment in a join. */
|
|
21
|
+
export declare function sharedFragment(id: string): string;
|
|
22
|
+
/**
|
|
23
|
+
* The result of `placedStack`.
|
|
24
|
+
*
|
|
25
|
+
* - `ok: true`: `stack` is the placed stack. `cost` is the expected cost of a month. `shared` has the `id` of each shared fragment of the stack.
|
|
26
|
+
* - `ok: false`: `findings` has the faults of the choice, or the findings of the join of the fragments.
|
|
27
|
+
*/
|
|
28
|
+
export type Placed = {
|
|
29
|
+
readonly ok: true;
|
|
30
|
+
readonly stack: Stack;
|
|
31
|
+
readonly cost: number;
|
|
32
|
+
readonly shared: readonly string[];
|
|
33
|
+
} | {
|
|
34
|
+
readonly ok: false;
|
|
35
|
+
readonly findings: readonly StackJoinFinding[];
|
|
36
|
+
};
|
|
37
|
+
/**
|
|
38
|
+
* This function gives the placed stack of one choice.
|
|
39
|
+
*
|
|
40
|
+
* - The fragments are the base stack with no placement layer, the chosen candidate of each slot, then each shared fragment that a chosen candidate uses.
|
|
41
|
+
* - A shared fragment is one fragment, also when two or more chosen candidates use it. Thus the stack counts a shared cause of failure one time.
|
|
42
|
+
* - `joinStacks` of the core joins the fragments. Each add-on of `joiners` joins its layer, for example the chances of `risk/1`.
|
|
43
|
+
* - The expected cost is the sum of the costs of the chosen candidates and of their shared fragments.
|
|
44
|
+
*
|
|
45
|
+
* A fault of the choice gives no join. The function is pure, and it does not change the layer or the stack.
|
|
46
|
+
*
|
|
47
|
+
* @param layer - The placement layer
|
|
48
|
+
* @param stack - The base stack. A placement layer of the stack is not part of the placed stack.
|
|
49
|
+
* @param choice - The key of the candidate of each slot
|
|
50
|
+
* @param joiners - The add-ons that join the layers of the fragments, for example the risk add-on and the spend add-on
|
|
51
|
+
* @returns The placed stack and its cost, or the findings
|
|
52
|
+
*/
|
|
53
|
+
export declare function placedStack(layer: PlacementLayer, stack: Stack, choice: Choice, joiners: readonly LayerJoiner<unknown>[]): Placed;
|
|
54
|
+
/** The name of the strategy space of a placement. A config of the search names the space with it. */
|
|
55
|
+
export declare const PLACEMENT_ENGINE = "stack-placement";
|
|
56
|
+
/** The name and the version of the evaluation of a choice. It is part of the `id` of a run. */
|
|
57
|
+
export declare const PLACEMENT_EVALUATOR = "stack-placement/1";
|
|
58
|
+
/** The objectives of a plan: the expected cost of a month, as low as possible. And the chance that the part works, as high as possible. */
|
|
59
|
+
export declare const PLACEMENT_OBJECTIVES: readonly Objective[];
|
|
60
|
+
/**
|
|
61
|
+
* These are the names of the breaks of a choice. A choice with a break is not on the front.
|
|
62
|
+
*
|
|
63
|
+
* - `join`: the choice has a fault, or its fragments do not join into one stack.
|
|
64
|
+
* - `measure`: a measure throws a `RangeError` for the placed stack. Or it gives a value out of its range.
|
|
65
|
+
* - `cost`: the expected cost is more than the limit `cost`.
|
|
66
|
+
* - `bound`: the bound of the cost of a month is more than the limit `bound`, or a service has no bound.
|
|
67
|
+
* - `chance`: the chance that the part works is less than the limit `chance`.
|
|
68
|
+
*/
|
|
69
|
+
export declare const PLAN_BREAKS: readonly ["join", "measure", "cost", "bound", "chance"];
|
|
70
|
+
/** A name of `PLAN_BREAKS`. */
|
|
71
|
+
export type PlanBreak = (typeof PLAN_BREAKS)[number];
|
|
72
|
+
/** The defaults of a plan. */
|
|
73
|
+
export declare const PLAN_DEFAULTS: {
|
|
74
|
+
readonly evaluations: 2000;
|
|
75
|
+
readonly seed: "stack-placement";
|
|
76
|
+
readonly importance: 5;
|
|
77
|
+
};
|
|
78
|
+
/** The relative tolerance of a comparison with a limit. Thus a sum with a rounding error does not break a limit. */
|
|
79
|
+
export declare const LIMIT_TOLERANCE = 1e-9;
|
|
80
|
+
/**
|
|
81
|
+
* The steps of the values that the search compares: a cost to 1e-9 of the currency, a chance to 1e-12. Two choices that give
|
|
82
|
+
* one true value can give floats with a different rounding error. With these steps, such choices tie, and the front keeps each.
|
|
83
|
+
* A row keeps the value before the step.
|
|
84
|
+
*/
|
|
85
|
+
export declare const OBJECTIVE_STEPS: {
|
|
86
|
+
readonly cost: 1e-9;
|
|
87
|
+
readonly chance: 1e-12;
|
|
88
|
+
};
|
|
89
|
+
/** The importance of one part for a chance, for example the Birnbaum importance of `stack-risk`. */
|
|
90
|
+
export interface PartWeight {
|
|
91
|
+
/** The `id` of the part. */
|
|
92
|
+
readonly part: string;
|
|
93
|
+
/** The chance when the part works, minus the chance when the part fails. */
|
|
94
|
+
readonly importance: number;
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* The reading of a chance measure. The value NaN tells that the measure cannot decide, for example at the end of a budget of steps.
|
|
98
|
+
* The search counts such a choice as unread, and the front does not have it.
|
|
99
|
+
*/
|
|
100
|
+
export interface ChanceReading {
|
|
101
|
+
/** The chance that the part works, from 0 to 1, or NaN. */
|
|
102
|
+
readonly value: number;
|
|
103
|
+
/** The most important parts for the chance, from the largest importance. */
|
|
104
|
+
readonly importance?: readonly PartWeight[] | undefined;
|
|
105
|
+
/** The parts that the measure takes as parts that work, because it has no chance for them. */
|
|
106
|
+
readonly assumed?: readonly string[] | undefined;
|
|
107
|
+
}
|
|
108
|
+
/** The reading of a bound measure: the largest cost of a month, and the part of each service with no bound. */
|
|
109
|
+
export interface BoundReading {
|
|
110
|
+
/** The sum of the largest costs of the services with a bound, in the currency of the layer. */
|
|
111
|
+
readonly bounded: number;
|
|
112
|
+
/** The part of each service with no bound. With one or more, the cost of the placed stack has no bound. */
|
|
113
|
+
readonly open: readonly string[];
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* The measure of the chance that the part `part` of a placed stack works. The caller makes it, for example from `worksChance` of `stack-risk`.
|
|
117
|
+
* A measure throws a `RangeError` for a stack that it refuses.
|
|
118
|
+
*/
|
|
119
|
+
export type ChanceMeasure = (stack: Stack, part: string) => number | ChanceReading;
|
|
120
|
+
/** The measure of the bound of the cost of a month of a placed stack, for example from `monthTotal` of `stack-spend`. */
|
|
121
|
+
export type BoundMeasure = (stack: Stack) => BoundReading;
|
|
122
|
+
/** The measure of the expected cost of a month of a placed stack. */
|
|
123
|
+
export type CostMeasure = (stack: Stack) => number;
|
|
124
|
+
/**
|
|
125
|
+
* The options of `planPlacement`. The add-on knows no other add-on. Thus the caller gives the joiners and the measures.
|
|
126
|
+
* A host, a site or a test makes them, for example from the add-ons of risk and spend.
|
|
127
|
+
*/
|
|
128
|
+
export interface PlanOptions {
|
|
129
|
+
/** The add-ons that join the layers of the fragments, one for each layer of a fragment. */
|
|
130
|
+
readonly joiners: readonly LayerJoiner<unknown>[];
|
|
131
|
+
/** The measure of the chance. */
|
|
132
|
+
readonly chance: ChanceMeasure;
|
|
133
|
+
/** The measure of the bound of the cost. A layer with the limit `bound` needs it. Without it, each row has the bound `null`. */
|
|
134
|
+
readonly bound?: BoundMeasure | undefined;
|
|
135
|
+
/** The measure of the expected cost. The default is the sum of the costs of the chosen candidates and of their shared fragments. */
|
|
136
|
+
readonly cost?: CostMeasure | undefined;
|
|
137
|
+
/** The most evaluations. A space with this count of choices or less gets a grid of each choice. A larger space gets a genetic search. The default is 2000. */
|
|
138
|
+
readonly evaluations?: number | undefined;
|
|
139
|
+
/** The seed of a genetic search: a whole number, or a name. The default is `stack-placement`. */
|
|
140
|
+
readonly seed?: number | string | undefined;
|
|
141
|
+
/** The count of the most important parts in each row of the front. The default is 5. */
|
|
142
|
+
readonly importance?: number | undefined;
|
|
143
|
+
}
|
|
144
|
+
/** One row of the front of a plan: a choice that keeps each limit, and its measures. */
|
|
145
|
+
export interface PlacementRow {
|
|
146
|
+
/** The `id` of the config of the choice in the search. */
|
|
147
|
+
readonly config: string;
|
|
148
|
+
/** The key of the candidate of each slot. An empty optional slot has the value `null`. */
|
|
149
|
+
readonly choice: Choice;
|
|
150
|
+
/** The source of each chosen candidate with a source, by the `id` of its slot. */
|
|
151
|
+
readonly sources: Readonly<Record<string, string>>;
|
|
152
|
+
/** The `id` of each shared fragment of the placed stack. */
|
|
153
|
+
readonly shared: readonly string[];
|
|
154
|
+
/** The expected cost of a month. */
|
|
155
|
+
readonly cost: number;
|
|
156
|
+
/** The chance that the part of the layer works. */
|
|
157
|
+
readonly chance: number;
|
|
158
|
+
/** The reading of the bound measure, or `null` when the plan has no bound measure. */
|
|
159
|
+
readonly bound: BoundReading | null;
|
|
160
|
+
/** The most important parts for the chance, from the reading of the chance measure. */
|
|
161
|
+
readonly importance: readonly PartWeight[];
|
|
162
|
+
/** The parts that the chance measure takes as parts that work. */
|
|
163
|
+
readonly assumed: readonly string[];
|
|
164
|
+
}
|
|
165
|
+
/**
|
|
166
|
+
* The plan of a placement.
|
|
167
|
+
*
|
|
168
|
+
* - `method`: `grid` for each choice of the space, `evolve` for a genetic search of a larger space.
|
|
169
|
+
* - `front`: the choices that no other choice beats on the cost and on the chance, from the lowest cost.
|
|
170
|
+
* Rows with one cost are from the largest chance. Rows with equal values are in the order of their config.
|
|
171
|
+
* - `breaks`: the count of the evaluated choices with each break, for the breaks with one or more choices.
|
|
172
|
+
*/
|
|
173
|
+
export interface PlacementPlan {
|
|
174
|
+
readonly method: "grid" | "evolve";
|
|
175
|
+
/** The `id` of the run of the search, from the space, the enumeration, the objectives and the evaluator. */
|
|
176
|
+
readonly run: string;
|
|
177
|
+
/** The count of the evaluated choices. */
|
|
178
|
+
readonly evaluations: number;
|
|
179
|
+
/** The count of the choices of the space, as a decimal text. The count can be larger than the largest safe number. */
|
|
180
|
+
readonly size: string;
|
|
181
|
+
readonly counts: SweepCounts;
|
|
182
|
+
readonly front: readonly PlacementRow[];
|
|
183
|
+
readonly breaks: Readonly<Partial<Record<PlanBreak, number>>>;
|
|
184
|
+
}
|
|
185
|
+
/**
|
|
186
|
+
* This function gives the strategy space of a layer. Each slot is one stage, and each candidate is one option with no params.
|
|
187
|
+
* An optional slot is an optional stage.
|
|
188
|
+
*/
|
|
189
|
+
export declare function placementSpace(layer: PlacementLayer): StrategySpace;
|
|
190
|
+
/** This function gives the choice of a config of the space of a layer. A stage with no option gives the value `null`. */
|
|
191
|
+
export declare function choiceOf(config: StrategyConfig): Choice;
|
|
192
|
+
/**
|
|
193
|
+
* This function gives the problems of the options of a plan for a layer. A problem is a bad count, a measure that is not a function,
|
|
194
|
+
* or the limit `bound` with no bound measure.
|
|
195
|
+
*
|
|
196
|
+
* @param options - The options of a plan
|
|
197
|
+
* @param layer - The placement layer, for the check of its limits
|
|
198
|
+
* @returns The problems, or an empty list for good options
|
|
199
|
+
*/
|
|
200
|
+
export declare function planProblems(options: PlanOptions, layer?: PlacementLayer): string[];
|
|
201
|
+
/**
|
|
202
|
+
* This function gives the plan of a placement: the front of the choices, with the expected cost against the chance that the part works.
|
|
203
|
+
*
|
|
204
|
+
* - Each choice gives one placed stack, from `placedStack`. The measures of the options give its cost, its chance and its bound.
|
|
205
|
+
* - A space with the count `evaluations` of choices or less gets a grid of each choice. A larger space gets a seeded genetic search.
|
|
206
|
+
* - A choice that breaks a limit, or whose stack has a fault, is not on the front. `breaks` counts each break.
|
|
207
|
+
*
|
|
208
|
+
* The result is deterministic when each measure is deterministic: one layer, one stack and one set of options give one plan.
|
|
209
|
+
*
|
|
210
|
+
* @param layer - The placement layer
|
|
211
|
+
* @param stack - The base stack
|
|
212
|
+
* @param options - The joiners, the measures and the options of the search
|
|
213
|
+
* @returns The plan
|
|
214
|
+
* @throws RangeError when an option is bad, or when the space of the layer has a problem, for example a slot with no candidate
|
|
215
|
+
*/
|
|
216
|
+
export declare function planPlacement(layer: PlacementLayer, stack: Stack, options: PlanOptions): PlacementPlan;
|
|
217
|
+
/**
|
|
218
|
+
* These are the codes of the gate.
|
|
219
|
+
*
|
|
220
|
+
* - `part-unknown` (error): the part of the layer is not a part of the base stack.
|
|
221
|
+
* - `slot-twice` (error): two or more slots have one `id`.
|
|
222
|
+
* - `slot-part` (error): the `id` of a slot is a part of the base stack. A candidate gives that part.
|
|
223
|
+
* - `slot-unneeded` (warning): no part of the base stack names the `id` of a slot in a need.
|
|
224
|
+
* - `slot-no-candidate` (error): a slot has no candidate.
|
|
225
|
+
* - `candidate-twice` (error): two or more candidates of a slot have one key.
|
|
226
|
+
* - `candidate-part` (error): the stack of a candidate has no part with the `id` of its slot.
|
|
227
|
+
* - `cost-range` (error): a cost is not a finite number of 0 or more.
|
|
228
|
+
* - `shared-twice` (error): two or more shared fragments have one `id`.
|
|
229
|
+
* - `shared-unknown` (error): a candidate uses a shared fragment that the layer does not have.
|
|
230
|
+
* - `shared-unused` (warning): no candidate uses a shared fragment.
|
|
231
|
+
* - `limit-range` (error): a limit of cost is not a finite number of 0 or more. Or the limit of chance is not from 0 to 1.
|
|
232
|
+
*/
|
|
233
|
+
export declare const PLACEMENT_CODES: readonly ["part-unknown", "slot-twice", "slot-part", "slot-unneeded", "slot-no-candidate", "candidate-twice", "candidate-part", "cost-range", "shared-twice", "shared-unknown", "shared-unused", "limit-range"];
|
|
234
|
+
/** A code of `PLACEMENT_CODES`. */
|
|
235
|
+
export type PlacementCode = (typeof PLACEMENT_CODES)[number];
|
|
236
|
+
/** A fault of the gate of a placement layer. */
|
|
237
|
+
export interface PlacementFault extends Fault {
|
|
238
|
+
readonly code: PlacementCode;
|
|
239
|
+
}
|
|
240
|
+
/**
|
|
241
|
+
* This function gives each fault of a placement layer for its base stack. A list with no error tells that the gate passes.
|
|
242
|
+
*
|
|
243
|
+
* The gate examines the slots, the candidates, the shared fragments, the costs and the limits. It does not examine the
|
|
244
|
+
* layers of a fragment: the gates of their add-ons examine each placed stack. The faults are in the order of the layer.
|
|
245
|
+
* The function is pure.
|
|
246
|
+
*
|
|
247
|
+
* @param layer - The placement layer
|
|
248
|
+
* @param stack - The base stack, with the layer
|
|
249
|
+
* @returns The faults
|
|
250
|
+
*/
|
|
251
|
+
export declare function checkPlacement(layer: PlacementLayer, stack: Stack): PlacementFault[];
|
|
252
|
+
/**
|
|
253
|
+
* This function joins the placement layers of the fragments of a stack into one layer.
|
|
254
|
+
*
|
|
255
|
+
* - The layer has one part and one currency. A fragment with a different value is a fault.
|
|
256
|
+
* - Each limit has one value. A fragment with no value takes the value of the others.
|
|
257
|
+
* - The slots and the shared fragments are in the order of the fragments. A slot or a shared fragment of two or more fragments is a fault.
|
|
258
|
+
*
|
|
259
|
+
* The function is pure, and it changes no layer. The gate `checkPlacement` examines the joined layer afterward.
|
|
260
|
+
*
|
|
261
|
+
* @param pieces - The layers, with the name of the fragment of each one, in the order of the fragments.
|
|
262
|
+
* @returns The joined layer, or the faults of the join. An empty list of layers is a fault.
|
|
263
|
+
*/
|
|
264
|
+
export declare function joinPlacement(pieces: readonly LayerPiece<PlacementLayer>[]): LayerParse<PlacementLayer>;
|
|
265
|
+
/** The date of the add-ons of the sample. */
|
|
266
|
+
export declare const SAMPLE_TODAY = "2026-11-18";
|
|
267
|
+
/** The base stack of the sample. The function `send` works when one of the parts `copy-a` and `copy-b` works. */
|
|
268
|
+
export declare const SAMPLE_BASE: Stack;
|
|
269
|
+
/**
|
|
270
|
+
* The sample placement layer. Each name and each number is an example.
|
|
271
|
+
* The slot `copy-a` needs a candidate, and the slot `copy-b` can stay empty. The two candidates of a slot use two different providers.
|
|
272
|
+
*/
|
|
273
|
+
export declare const SAMPLE_PLACEMENT: PlacementLayer;
|
|
274
|
+
/** The base stack of the sample with the sample placement layer. */
|
|
275
|
+
export declare const SAMPLE_STACK: Stack;
|
|
276
|
+
export { Candidate, Choice, PLACEMENT_SCHEMA, PlacementLayer, PlacementLimits, Shared, Slot };
|
|
277
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","names":[],"sources":["../src/place.ts","../src/plan.ts","../src/check.ts","../src/join.ts","../src/sample.ts"],"mappings":";;;;;;;;;;;;qBAaa;;YAGD,qBAAqB;;qBAGpB;;wBAGG,aAAa;;wBAKb,eAAe;;;;;;;YAUnB;WACG;WAAmB,OAAO;WAAgB;WAAuB;;WACjE;WAAoB,mBAAmB;;;;;;;;;;;;;;;;;;wBAoCtC,YAAY,OAAO,gBAAgB,OAAO,OAAO,QAAQ,QAAQ,kBAAkB,yBAAyB;;qBClE/G;;qBAGA;;qBAGA,+BAA+B;;;;;;;;;;qBAc/B;;YAGD,oBAAoB;;qBAGnB;WAA0B;WAA4B;WAAkC;;;qBAGxF;;;;;;qBAOA;WAA4B;WAAqB;;;iBAG7C;;WAEN;;WAEA;;;;;;iBAOM;;WAEN;;WAEA,sBAAsB;;WAEtB;;;iBAIM;;WAEN;;WAEA;;;;;;YAOC,iBAAiB,OAAO,OAAO,0BAA0B;;YAGzD,gBAAgB,OAAO,UAAU;;YAGjC,eAAe,OAAO;;;;;iBAMjB;;WAEN,kBAAkB;;WAElB,QAAQ;;WAER,QAAQ;;WAER,OAAO;;WAEP;;WAEA;;WAEA;;;iBAIM;;WAEN;;WAEA,QAAQ;;WAER,SAAS,SAAS;;WAElB;;WAEA;;WAEA;;WAEA,OAAO;;WAEP,qBAAqB;;WAErB;;;;;;;;;;iBAWM;WACN;;WAEA;;WAEA;;WAEA;WACA,QAAQ;WACR,gBAAgB;WAChB,QAAQ,SAAS,QAAQ,OAAO;;;;;;wBAO3B,eAAe,OAAO,iBAAiB;;wBAcvC,SAAS,QAAQ,iBAAiB;;;;;;;;;wBAgClC,aAAa,SAAS,aAAa,QAAQ;;;;;;;;;;;;;;;;wBA+C3C,cAAc,OAAO,gBAAgB,OAAO,OAAO,SAAS,cAAc;;;;;;;;;;;;;;;;;qBCpO7E;;YA6BD,wBAAwB;;iBAGnB,uBAAuB;WAC7B,MAAM;;;;;;;;;;;;;wBA0BD,eAAe,OAAO,gBAAgB,OAAO,QAAQ;;;;;;;;;;;;;wBC/DrD,cAAc,iBAAiB,WAAW,oBAAoB,WAAW;;qBCX5E;;qBA6BA,aAAa;;;;;qBASb,kBAAkB;;qBAYlB,cAAc"}
|