@gadicc/loom 1.19.0 → 1.21.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/README.md +10 -3
- package/THIRD_PARTY_NOTICES.md +11 -10
- package/esm/src/cli/externalSkills.d.ts.map +1 -1
- package/esm/src/cli/externalSkills.js +18 -0
- package/esm/src/cli/mod.d.ts.map +1 -1
- package/esm/src/cli/mod.js +216 -6
- package/esm/src/next/jobs/run.d.ts +7 -0
- package/esm/src/next/jobs/run.d.ts.map +1 -1
- package/esm/src/next/jobs/run.js +48 -29
- package/esm/src/next/jobs/runRequest.d.ts +19 -0
- package/esm/src/next/jobs/runRequest.d.ts.map +1 -0
- package/esm/src/next/jobs/runRequest.js +76 -0
- package/package.json +2 -2
- package/script/src/cli/externalSkills.d.ts.map +1 -1
- package/script/src/cli/externalSkills.js +18 -0
- package/script/src/cli/mod.d.ts.map +1 -1
- package/script/src/cli/mod.js +215 -5
- package/script/src/next/jobs/run.d.ts +7 -0
- package/script/src/next/jobs/run.d.ts.map +1 -1
- package/script/src/next/jobs/run.js +51 -29
- package/script/src/next/jobs/runRequest.d.ts +19 -0
- package/script/src/next/jobs/runRequest.d.ts.map +1 -0
- package/script/src/next/jobs/runRequest.js +81 -0
- package/skills/loom/SKILL.md +10 -0
- package/skills/loom-jobs/SKILL.md +28 -3
- package/skills/loom-torvalds-review/SKILL.md +116 -0
- package/skills/loom-torvalds-review/agents/openai.yaml +4 -0
- package/skills/loom-torvalds-review/references/context-profiles.md +156 -0
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.DEFAULT_JOBS_RUN_REQUEST_METHOD = void 0;
|
|
4
|
+
exports.buildJobsRunSearchParams = buildJobsRunSearchParams;
|
|
5
|
+
exports.getJobsRunResponseErrorMessage = getJobsRunResponseErrorMessage;
|
|
6
|
+
const MAX_JOBS_RUN_ERROR_BODY_LENGTH = 1_000;
|
|
7
|
+
/** The compatibility transport used when a run panel does not choose one. */
|
|
8
|
+
exports.DEFAULT_JOBS_RUN_REQUEST_METHOD = "GET";
|
|
9
|
+
/**
|
|
10
|
+
* Preserves compatibility query values while overlaying declared form fields.
|
|
11
|
+
* Empty non-boolean fields remove an existing value instead of sending it.
|
|
12
|
+
*/
|
|
13
|
+
function buildJobsRunSearchParams(queryString, definitions, formValues) {
|
|
14
|
+
const searchParams = new URLSearchParams(queryString ?? "");
|
|
15
|
+
if (!definitions)
|
|
16
|
+
return searchParams;
|
|
17
|
+
for (const [key, definition] of Object.entries(definitions)) {
|
|
18
|
+
const value = formValues[key] ?? "";
|
|
19
|
+
if (definition.type === "boolean") {
|
|
20
|
+
searchParams.set(key, value === "true" ? "true" : "false");
|
|
21
|
+
}
|
|
22
|
+
else if (value !== "") {
|
|
23
|
+
searchParams.set(key, value);
|
|
24
|
+
}
|
|
25
|
+
else {
|
|
26
|
+
searchParams.delete(key);
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
return searchParams;
|
|
30
|
+
}
|
|
31
|
+
function safeJsonStringify(value) {
|
|
32
|
+
try {
|
|
33
|
+
return JSON.stringify(value);
|
|
34
|
+
}
|
|
35
|
+
catch {
|
|
36
|
+
return String(value);
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
function boundJobsRunErrorBody(value) {
|
|
40
|
+
const normalized = value.trim();
|
|
41
|
+
if (normalized.length <= MAX_JOBS_RUN_ERROR_BODY_LENGTH) {
|
|
42
|
+
return normalized;
|
|
43
|
+
}
|
|
44
|
+
return `${normalized.slice(0, MAX_JOBS_RUN_ERROR_BODY_LENGTH - 3)}...`;
|
|
45
|
+
}
|
|
46
|
+
function getJsonErrorBody(body) {
|
|
47
|
+
try {
|
|
48
|
+
const parsed = JSON.parse(body);
|
|
49
|
+
if (typeof parsed !== "object" ||
|
|
50
|
+
parsed === null ||
|
|
51
|
+
!("error" in parsed)) {
|
|
52
|
+
return null;
|
|
53
|
+
}
|
|
54
|
+
const error = parsed.error;
|
|
55
|
+
return typeof error === "string" ? error : safeJsonStringify(error);
|
|
56
|
+
}
|
|
57
|
+
catch {
|
|
58
|
+
return null;
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* Builds a bounded plain-text message for a failed jobs runner response.
|
|
63
|
+
* Response content is returned only as text so React escapes it when rendered.
|
|
64
|
+
*/
|
|
65
|
+
async function getJobsRunResponseErrorMessage(response) {
|
|
66
|
+
const fallback = `Request failed with status ${response.status}`;
|
|
67
|
+
try {
|
|
68
|
+
const body = await response.text();
|
|
69
|
+
if (!body.trim())
|
|
70
|
+
return fallback;
|
|
71
|
+
const contentType = response.headers.get("content-type")?.toLowerCase();
|
|
72
|
+
const detail = contentType?.includes("application/json")
|
|
73
|
+
? getJsonErrorBody(body) ?? body
|
|
74
|
+
: body;
|
|
75
|
+
const boundedDetail = boundJobsRunErrorBody(detail);
|
|
76
|
+
return boundedDetail ? `${fallback}: ${boundedDetail}` : fallback;
|
|
77
|
+
}
|
|
78
|
+
catch {
|
|
79
|
+
return fallback;
|
|
80
|
+
}
|
|
81
|
+
}
|
package/skills/loom/SKILL.md
CHANGED
|
@@ -118,6 +118,16 @@ as database rows, job/run artifacts, checkpoints, logs, saved metadata, and the
|
|
|
118
118
|
exact command or UI path used. Treat the provider or system's recorded response
|
|
119
119
|
as more authoritative than a generic mapped error when deciding what failed.
|
|
120
120
|
|
|
121
|
+
## Context-aware code review
|
|
122
|
+
|
|
123
|
+
- For code and design reviews, use `loom-torvalds-review` before the external
|
|
124
|
+
`linus-torvalds-skill` when both are active.
|
|
125
|
+
- Treat the Loom companion as the precedence and context layer. It maps the
|
|
126
|
+
upstream kernel-derived questions to web-app, shared-library/CLI, systems, or
|
|
127
|
+
explicit-prototype work and disables literal low-level rules elsewhere.
|
|
128
|
+
- In normal Loom Next.js consumers, default to the web-application profile
|
|
129
|
+
without asking. Use different profiles path by path for a mixed diff.
|
|
130
|
+
|
|
121
131
|
## Documentation and comments
|
|
122
132
|
|
|
123
133
|
- Add JSDoc for new exported functions or methods when intent, key behavior, or
|
|
@@ -80,13 +80,38 @@ Use this skill when working on the shared jobs feature from a consuming app.
|
|
|
80
80
|
preserve the existing session/admin branch.
|
|
81
81
|
- Use `authorizeSessionOrApiKeyRequest` plus `completeApiKeyAuthorizedResponse`
|
|
82
82
|
for auditable response creation without buffering job streams.
|
|
83
|
-
-
|
|
84
|
-
|
|
83
|
+
- The shared admin runner accepts `requestMethod: "POST"`; new Loom scaffolds
|
|
84
|
+
prefer POST while the component's omitted/default method remains GET for
|
|
85
|
+
existing consumers. Declared job parameters remain query parameters under
|
|
86
|
+
either method.
|
|
87
|
+
- GET and POST route exports remain supported for external callers; a future
|
|
88
|
+
POST-only change requires a separate compatibility migration.
|
|
85
89
|
- The direct local runner imports the catalog and executes inside the trusted
|
|
86
90
|
shell process with local environment/database access. It remains API-key-free.
|
|
87
91
|
A future command that calls a deployed HTTP route is a remote client and must
|
|
88
92
|
authenticate.
|
|
89
93
|
|
|
94
|
+
## Browser runner boundaries
|
|
95
|
+
|
|
96
|
+
- Prefer `createJobsRunPage` or `JobsRunPanel` over an app-local executor. The
|
|
97
|
+
shared runner owns streaming, status, cancellation, declarative parameters,
|
|
98
|
+
bounded non-success details, and safe structured rendering hooks.
|
|
99
|
+
- Never import `@gadicc/loom/jobs/format` into a client component or any local
|
|
100
|
+
module reachable beneath a `"use client"` boundary. Its rich formatter uses
|
|
101
|
+
Node's `formatWithOptions` intentionally and remains valid for server routes,
|
|
102
|
+
CLI output, and text/HTML response formatting.
|
|
103
|
+
- Import `formatJobLogTime` from `@gadicc/loom/jobs/log` in browser code. Render
|
|
104
|
+
structured values with `JobsRunPanel`, its `renderLogValue` hook, or another
|
|
105
|
+
helper whose browser support is explicit.
|
|
106
|
+
- Keep executable job catalogs and server-only formatters in server modules. A
|
|
107
|
+
server wrapper may pass serializable job metadata to a client island, but the
|
|
108
|
+
metadata catalog it imports must stay dependency-free so executable or
|
|
109
|
+
Node-only modules cannot enter the browser graph transitively.
|
|
110
|
+
- Record a non-default admin transport in
|
|
111
|
+
`features.jobs.config.ui.requestMethod`; `loom check` follows the configured
|
|
112
|
+
run-page's local server-wrapper/client-island graph, verifies the shared
|
|
113
|
+
runner and request method, and reports browser-unsafe imports.
|
|
114
|
+
|
|
90
115
|
## Diagnosing queued work
|
|
91
116
|
|
|
92
117
|
- Distinguish the control-plane action that queues a job from the worker or
|
|
@@ -170,7 +195,7 @@ When adding or upgrading a job:
|
|
|
170
195
|
- Run `loom check` after changes.
|
|
171
196
|
- Confirm local wrappers still point at the configured shared modules.
|
|
172
197
|
- Confirm the jobs modules still use the shared helpers: `createJobsListPage`,
|
|
173
|
-
`createJobsRunPage`, and `createJobsRouteHandler`.
|
|
198
|
+
either `createJobsRunPage` or `JobsRunPanel`, and `createJobsRouteHandler`.
|
|
174
199
|
- Confirm executable catalog entries use `createLazyJob` and the metadata
|
|
175
200
|
catalog does not import job implementations.
|
|
176
201
|
- Confirm the authoritative `job` task runs the direct runner through
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: loom-torvalds-review
|
|
3
|
+
description: Context-aware code and design review for Loom consumer projects, adapting the linus-torvalds-skill reviewer method to the actual runtime and product contract. Use when reviewing a diff or pull request, assessing an API or architecture change, checking a refactor or bug fix, challenging a performance claim, or doing the final engineering review of implementation work, especially in Next.js and other web applications.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Loom Torvalds Review
|
|
7
|
+
|
|
8
|
+
Apply the useful habits distilled by the upstream
|
|
9
|
+
[`mte90/linus-torvalds-skill`](https://github.com/mte90/linus-torvalds-skill):
|
|
10
|
+
correctness, simple data flow, compatibility, evidence, focused changes, and
|
|
11
|
+
clear technical reasoning. Do not treat Linux kernel implementation details,
|
|
12
|
+
corpus-derived severity rates, or Linus Torvalds's persona as universal rules.
|
|
13
|
+
|
|
14
|
+
## Establish authority and context
|
|
15
|
+
|
|
16
|
+
1. Read the repository instructions. In a Loom consumer, use the `loom` skill
|
|
17
|
+
first and read `loom.json`.
|
|
18
|
+
2. Treat this skill as the context and precedence layer for
|
|
19
|
+
`linus-torvalds-skill`. When the two disagree, follow this skill and the
|
|
20
|
+
repository's explicit contract.
|
|
21
|
+
3. For a code or design review, read
|
|
22
|
+
`.agents/skills/linus-torvalds-skill/SKILL.md` when it is installed. Treat
|
|
23
|
+
its triggers as a source of review questions, not automatic findings. Do not
|
|
24
|
+
load or imitate an upstream `soul` or persona file.
|
|
25
|
+
4. If the upstream skill is not installed, continue with this skill. Mention
|
|
26
|
+
`loom add skills` only when the missing deeper review catalog materially
|
|
27
|
+
limits the task.
|
|
28
|
+
|
|
29
|
+
## Select profiles before reviewing
|
|
30
|
+
|
|
31
|
+
Classify each changed area; a mixed diff may need more than one profile.
|
|
32
|
+
|
|
33
|
+
- Use **web application** by default when `loom.json` identifies Next.js or the
|
|
34
|
+
project uses a browser UI, HTTP handlers, server actions, queues, or a web
|
|
35
|
+
database. This is Loom's normal consumer profile.
|
|
36
|
+
- Use **shared library or CLI** for package exports, command behavior, generated
|
|
37
|
+
output, manifests, and cross-runtime tooling.
|
|
38
|
+
- Use **systems or native** only for native code, FFI, shared-memory workers,
|
|
39
|
+
runtime internals, or other code where memory layout and low-level
|
|
40
|
+
synchronization genuinely govern correctness.
|
|
41
|
+
- Add **prototype** only when the project explicitly identifies the code as
|
|
42
|
+
disposable or exploratory. Never use that label to relax security, privacy,
|
|
43
|
+
authorization, or real-user data integrity.
|
|
44
|
+
|
|
45
|
+
Read [references/context-profiles.md](references/context-profiles.md) for the
|
|
46
|
+
selected profiles and for the list of upstream checks that are disabled unless
|
|
47
|
+
their prerequisites are present.
|
|
48
|
+
|
|
49
|
+
## Apply Loom's precedence
|
|
50
|
+
|
|
51
|
+
Resolve competing concerns in this order:
|
|
52
|
+
|
|
53
|
+
1. Security, privacy, authorization, data integrity, and behavioral correctness.
|
|
54
|
+
2. Explicit product requirements and supported user, API, data, and semver
|
|
55
|
+
contracts.
|
|
56
|
+
3. Reproducible evidence, operability, reversibility, and failure recovery.
|
|
57
|
+
4. Simplicity, readable data flow, and maintainability.
|
|
58
|
+
5. Performance against an explicit budget or realistic measurement.
|
|
59
|
+
6. Local style and cosmetic consistency.
|
|
60
|
+
|
|
61
|
+
Move performance higher only when the repository defines it as a hard contract
|
|
62
|
+
and the change has relevant evidence. Never rank style, micro-optimization, or
|
|
63
|
+
kernel convention above security or supported users.
|
|
64
|
+
|
|
65
|
+
## Review the change
|
|
66
|
+
|
|
67
|
+
1. Establish the requested behavior, changed scope, supported environments,
|
|
68
|
+
public boundaries, and trust boundaries. For a review-only request, inspect
|
|
69
|
+
and report; do not modify the code.
|
|
70
|
+
2. Trace the data and state transitions before judging local syntax. Include
|
|
71
|
+
client/server boundaries, persistence, retries, caching, and partial failure
|
|
72
|
+
where relevant.
|
|
73
|
+
3. Apply only upstream triggers whose prerequisites exist in this context.
|
|
74
|
+
Translate the underlying concern into the project's idioms instead of copying
|
|
75
|
+
a kernel remedy.
|
|
76
|
+
4. Check the actual diff for unrelated churn, compatibility changes, hidden
|
|
77
|
+
costs, unnecessary special cases, inaccurate docs, and missing cleanup
|
|
78
|
+
created by the change.
|
|
79
|
+
5. Seek proportionate evidence. Reproduce correctness failures; use realistic
|
|
80
|
+
measurements for performance claims; run the repository's relevant tests,
|
|
81
|
+
typecheck, lint, and build when implementation work is in scope.
|
|
82
|
+
6. Derive severity from concrete impact and reachability. Ignore the upstream
|
|
83
|
+
corpus percentages when deciding whether a finding blocks the change.
|
|
84
|
+
|
|
85
|
+
## Keep the method humane and practical
|
|
86
|
+
|
|
87
|
+
- Be direct, specific, and technically confident, but do not role-play Linus,
|
|
88
|
+
use profanity, insult people, or manufacture outrage. Critique code and
|
|
89
|
+
decisions, never the author.
|
|
90
|
+
- Prefer a root-cause fix, but allow a contained mitigation, compatibility
|
|
91
|
+
bridge, feature flag, or staged migration when external constraints or an
|
|
92
|
+
incident make that the safer engineering choice. State the residual risk and
|
|
93
|
+
follow-up condition.
|
|
94
|
+
- Do not reject a helper, option object, opaque type, framework abstraction, or
|
|
95
|
+
feature flag by category. Ask whether it makes the common path clearer,
|
|
96
|
+
preserves ownership boundaries, or represents proven variation.
|
|
97
|
+
- Do not import C or kernel conventions into TypeScript APIs. Use the target
|
|
98
|
+
language, framework, deployment platform, and repository conventions.
|
|
99
|
+
- Treat formatter-owned whitespace, contractions, and personal taste as
|
|
100
|
+
non-findings unless they violate an explicit local rule or impair meaning.
|
|
101
|
+
|
|
102
|
+
## Report findings
|
|
103
|
+
|
|
104
|
+
Lead with actionable findings ordered by impact. For each finding, include:
|
|
105
|
+
|
|
106
|
+
- the smallest useful file and line span;
|
|
107
|
+
- the violated project contract or realistic failure mode;
|
|
108
|
+
- evidence that the behavior is reachable;
|
|
109
|
+
- a concrete direction for correction.
|
|
110
|
+
|
|
111
|
+
Separate blocking defects from suggestions. Do not inflate a speculative concern
|
|
112
|
+
into a finding. If no actionable findings remain, say so and identify any
|
|
113
|
+
material verification gap.
|
|
114
|
+
|
|
115
|
+
The review is complete when every finding is context-valid, evidence-backed, and
|
|
116
|
+
more useful than the kernel-flavored rule that prompted the question.
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
# Context profiles
|
|
2
|
+
|
|
3
|
+
Use the sections matching the changed paths. The core question is always the
|
|
4
|
+
same: what real contract or failure mode does this rule protect here?
|
|
5
|
+
|
|
6
|
+
## Web application profile
|
|
7
|
+
|
|
8
|
+
### Contracts and compatibility
|
|
9
|
+
|
|
10
|
+
- Treat HTTP shapes, database schemas, stored data, URLs, auth behavior, public
|
|
11
|
+
component/package APIs, and observable UI behavior as possible contracts.
|
|
12
|
+
- Distinguish public behavior from internal implementation. Internal code may
|
|
13
|
+
change freely when callers, persisted data, and user behavior remain intact.
|
|
14
|
+
- Evaluate compatibility through the project's versioning and migration model. A
|
|
15
|
+
coordinated migration or a documented major release is not equivalent to
|
|
16
|
+
silently breaking users.
|
|
17
|
+
- Prefer deprecation or compatibility bridges when they are cheaper and safer,
|
|
18
|
+
but do not preserve a security vulnerability or corrupt data for the sake of
|
|
19
|
+
compatibility.
|
|
20
|
+
|
|
21
|
+
### Error handling and recovery
|
|
22
|
+
|
|
23
|
+
- Use idiomatic exceptions, typed results, HTTP responses, error boundaries,
|
|
24
|
+
retries, and user-visible recovery. Do not require kernel-style integer error
|
|
25
|
+
codes.
|
|
26
|
+
- A process crash, unhandled rejection, lost mutation, or permanently stuck UI
|
|
27
|
+
may be the web equivalent of an unrecoverable kernel path. An assertion for a
|
|
28
|
+
true programmer invariant can still be appropriate.
|
|
29
|
+
- Review retry and fallback behavior for idempotency, duplicate effects,
|
|
30
|
+
cancellation, timeout, and misleading success states.
|
|
31
|
+
|
|
32
|
+
### Abstraction and state
|
|
33
|
+
|
|
34
|
+
- Judge components, hooks, services, repositories, adapters, and option objects
|
|
35
|
+
by ownership, reuse, testability, and whether they clarify a client/server or
|
|
36
|
+
provider boundary.
|
|
37
|
+
- Reject speculative layers with no present variation. Keep a small abstraction
|
|
38
|
+
when it prevents duplication, centralizes a contract, or isolates a volatile
|
|
39
|
+
dependency.
|
|
40
|
+
- Prefer data models and state machines that make impossible states difficult to
|
|
41
|
+
represent. Check loading, empty, error, stale, optimistic, and partial states
|
|
42
|
+
where the user can observe them.
|
|
43
|
+
|
|
44
|
+
### Concurrency and performance
|
|
45
|
+
|
|
46
|
+
- Translate concurrency into async races, database transactions, optimistic
|
|
47
|
+
concurrency, queues, idempotency keys, cache invalidation, and distributed
|
|
48
|
+
coordination. JavaScript's event loop does not remove those races.
|
|
49
|
+
- Apply lock, atomic, memory-ordering, and cache-line advice only to actual
|
|
50
|
+
shared-memory workers, native modules, or runtime internals.
|
|
51
|
+
- Measure what users or operators experience: latency distributions, Core Web
|
|
52
|
+
Vitals when relevant, request/query counts, bundle size, memory, cold starts,
|
|
53
|
+
queue throughput, or provider cost. Do not demand a benchmark for an unclaimed
|
|
54
|
+
and immaterial micro-optimization.
|
|
55
|
+
|
|
56
|
+
### Web security and usability
|
|
57
|
+
|
|
58
|
+
- Prioritize authentication and authorization separation, tenant isolation,
|
|
59
|
+
injection, XSS, CSRF, SSRF, unsafe redirects, secret exposure, cookie and
|
|
60
|
+
origin policy, cache leakage, upload/download boundaries, and untrusted input.
|
|
61
|
+
- Treat accessibility, destructive-action confirmation, and recoverable user
|
|
62
|
+
flows as correctness when they are part of the product contract.
|
|
63
|
+
- Prefer secure, private defaults. Require an explicit reason before a default
|
|
64
|
+
sends data externally, weakens access control, or exposes internal details.
|
|
65
|
+
|
|
66
|
+
### Testing and style
|
|
67
|
+
|
|
68
|
+
- Test the affected support matrix, not every browser and platform in existence.
|
|
69
|
+
Add production builds for framework, bundler, server/client-boundary, or
|
|
70
|
+
deployment-sensitive changes.
|
|
71
|
+
- Let the project formatter, linter, typechecker, and design system define
|
|
72
|
+
style. Whitespace and wording are findings only when they obscure meaning or
|
|
73
|
+
violate that contract.
|
|
74
|
+
|
|
75
|
+
## Shared library or CLI profile
|
|
76
|
+
|
|
77
|
+
- Treat exported types and functions, command flags, exit status, stdout/stderr,
|
|
78
|
+
generated files, config schemas, and documented runtime support as contracts.
|
|
79
|
+
- Preserve semver. Breaking changes are acceptable only through the repository's
|
|
80
|
+
declared release and migration path; additive compatibility is preferred.
|
|
81
|
+
- Use idiomatic errors for each runtime. Stable CLI exit codes and parseable
|
|
82
|
+
output matter, but a library does not need C's `0`/negative-error convention.
|
|
83
|
+
- Prefer portable Web APIs in Deno-first shared code when they meet the need.
|
|
84
|
+
Isolate unavoidable Node or native behavior and test the supported runtimes.
|
|
85
|
+
- Apply bisectability to the commits that will be shipped. A working tree need
|
|
86
|
+
not be valid at every keystroke, while each final commit should build and make
|
|
87
|
+
coherent sense when the repository requires that history quality.
|
|
88
|
+
- Require benchmarks only for performance claims or budgets that affect package
|
|
89
|
+
users. Include startup time, artifact size, throughput, memory, and generated
|
|
90
|
+
client-bundle impact when relevant.
|
|
91
|
+
|
|
92
|
+
## Systems or native profile
|
|
93
|
+
|
|
94
|
+
- Apply upstream memory-layout, lifetime, synchronization, atomics, executable
|
|
95
|
+
memory, ABI, and architecture advice when the implementation actually exposes
|
|
96
|
+
those concerns.
|
|
97
|
+
- Keep Loom's precedence and tone rules. Security and supported contracts still
|
|
98
|
+
outrank an unmeasured micro-optimization, and corpus percentages still do not
|
|
99
|
+
determine severity.
|
|
100
|
+
- Translate Linux-specific APIs to the target operating system and runtime.
|
|
101
|
+
`sysctl`, `seq_printf`, `READ_ONCE`, BKL, `execve`, and errno examples are
|
|
102
|
+
evidence for a principle, not portable remedies.
|
|
103
|
+
|
|
104
|
+
## Prototype modifier
|
|
105
|
+
|
|
106
|
+
- Relax long-term compatibility, exhaustive testing, and abstraction longevity
|
|
107
|
+
only when the prototype boundary is explicit and the code is not silently
|
|
108
|
+
becoming production infrastructure.
|
|
109
|
+
- Keep cheap diagnostics and a clear path to delete or replace the experiment.
|
|
110
|
+
- Do not relax security, privacy, authorization, billing integrity, or real-user
|
|
111
|
+
data protection merely because the feature is experimental.
|
|
112
|
+
|
|
113
|
+
## Upstream checks disabled by default
|
|
114
|
+
|
|
115
|
+
Do not report these as findings unless the stated prerequisite exists:
|
|
116
|
+
|
|
117
|
+
| Upstream check | Prerequisite or contextual translation |
|
|
118
|
+
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
|
119
|
+
| Return `0` or a negative error; never return byte counts | A C/ABI contract that defines those exact semantics. Use idiomatic typed errors elsewhere. |
|
|
120
|
+
| A write returning `0` means disk full | A write-like API whose documented contract gives zero that meaning. |
|
|
121
|
+
| Double underscores imply an internal-only symbol | A language or repository convention that explicitly assigns that meaning. |
|
|
122
|
+
| Opaque types are harmful | Callers genuinely require layout access. In most app and library APIs, encapsulation may be beneficial. |
|
|
123
|
+
| A new flag or option is inherently worse than an error | Compare clarity, compatibility, state-space growth, and target-language idiom. Feature flags can also support safe rollout. |
|
|
124
|
+
| A helper around one line is needless | The helper adds no domain name, policy, reuse, test seam, or ownership boundary. |
|
|
125
|
+
| A lock around one primitive must become an atomic | Shared-memory concurrency exists and the replacement preserves all ordering and compound invariants. |
|
|
126
|
+
| `READ_ONCE`, acquire/release, BKL, or tail-call/cache rules | Low-level memory ordering or instruction-cache behavior exists and is relevant on the target runtime. |
|
|
127
|
+
| Escaped stack pointers, executable pages, or per-CPU stack limits | Native/FFI/runtime code exposes manual lifetime, executable memory, or constrained stacks. |
|
|
128
|
+
| Hardware opt-in, sysctl, vsyscall, `seq_printf`, or `execve` advice | An equivalent platform capability exists. Preserve the principle, not the Linux mechanism. |
|
|
129
|
+
| RSA is categorically obsolete or post-quantum wording decides safety | Current project policy and authoritative cryptographic guidance establish the actual threat and migration requirement. |
|
|
130
|
+
| Contractions, blank lines, or nonstandard extensions are defects | Local style, parser, portability target, or readability provides a concrete reason. |
|
|
131
|
+
| Every low-level change needs every-platform testing | The affected supported environments require it. Test the real support matrix proportionately. |
|
|
132
|
+
| One-line commit header, blank line, then body is universal | The repository's commit and release tooling requires that shape. |
|
|
133
|
+
| Corpus reject/request-change percentages set severity | Never. Severity comes from current impact, likelihood, reachability, and recovery cost. |
|
|
134
|
+
|
|
135
|
+
## Translation examples
|
|
136
|
+
|
|
137
|
+
| Upstream principle | Web or package translation |
|
|
138
|
+
| ------------------------------------ | ------------------------------------------------------------------------------------------------------ |
|
|
139
|
+
| Do not break userspace | Preserve documented API/UI/data behavior or provide a semver and migration path. |
|
|
140
|
+
| Fix the data structure | Simplify the schema, state model, discriminated union, or ownership boundary before adding branches. |
|
|
141
|
+
| Do not crash for a recoverable error | Return a useful response, preserve user work, expose retry/recovery, and log enough to diagnose. |
|
|
142
|
+
| Show macro-benchmarks | Measure representative user journeys, server latency, queries, bundles, queues, or cost. |
|
|
143
|
+
| Avoid hidden-cost abstractions | Make network, database, rendering, serialization, and provider calls visible in naming and boundaries. |
|
|
144
|
+
| Keep patches bisectable | Produce coherent, buildable commits when commit history is part of the requested deliverable. |
|
|
145
|
+
|
|
146
|
+
## Root cause versus containment
|
|
147
|
+
|
|
148
|
+
Prefer the root cause when it is known and safely fixable. Accept containment
|
|
149
|
+
when it is the safer immediate move, including incident mitigation, upstream
|
|
150
|
+
provider defects, compatibility windows, risky data migrations, or phased
|
|
151
|
+
rollouts. A containment change should identify:
|
|
152
|
+
|
|
153
|
+
1. the failure it prevents;
|
|
154
|
+
2. why the root cause cannot be fixed safely in the same change;
|
|
155
|
+
3. its observability and rollback path;
|
|
156
|
+
4. the condition for removing or replacing it.
|